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PROGRAM DEVELOPMENT 


INTRODUCTION 


RSX-11M/M-PLUS operating systems provide complete facilities 
for all program development tasks. This module discusses program 
development in detail. MACRO-11, FORTRAN IV and FORTRAN IV-PLUS 


are emphasized since these languages are used in most 
applications. 


OBJECTIVES 


1. Assemble a MACRO-11 program. 


2. Compile a FORTRAN IV or FORTRAN IV-PLUS program. 


3. Task-build a program. 


4. Use the task map to obtain basic information. 


oe Run a task. 


RESOURCES 


1. Introduction to RSX-11M/M-PLUS 


2. RSX-11M/M-PLUS Command Language Manual 
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OVERVIEW 


Every task running on a computer is the solution to some 
well-defined problem. Someone Said we need a method of 
automatically generating payroll checks (the problem) and a 
software developer wrote a program that reads payroll records and 
generates paychecks for everyone on the payroll (the solution). 
Or, someone said we need a method of entering our Source code more 
efficiently and a programmer wrote a program that allows a 
terminal user to capture text into a file. 


Program development is the process by which a _e problem 
solution is translated from a human-understandable form into a 
machine-understandable form. Some of Kthe many steps necessary to 
do this conversion are shown in Figure 5-1. The process is longer 
than shown in the flowchart, but for our purposes, it begins at 
the point where the process needs the computer to complete the 
task. 


Once the problem to be solved is defined and a_ solution is 
designed and coded, the first step ( 1 in Figure 5-1) is to enter 
the code into a file. Source statements are entered using a text 
editor. Output from the editor is an ASCII file containing the 
source statements that comprise the program (or a module of the 
program) written with correct syntax required by the programming 
language. This file is the human-understandable form of the 
program and the first step in the translation of the program into 
-a machine-understandable form. 


The next step ( 2 in Figure 5-1) is to take the output file 
from the~ editing session and assemble or compile it with the 
appropriate language processor. Table 5-2 shows the language 
processors available on the RSX-11M/M-PLUS operating systems. The 
language processor performs the following functions: 


- checks the source statements for syntax errors 

- generates program addresses for relocatable machine code 
- produces a listing of the Source statements 

- lists any errors that exist 


The primary output from this step is an object file that contains 
object modules of relocatable machine instructions. 
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If there are no assembly errors, the next step in the process 
is to build (link) the actual runnable image of the program ( 3 in 
Figure 5-1). This may require linking the program with other 
object modules located in the user's UFD, or in user or system 
libraries, as shown in Figure 5-3. It is the Task Builder's job 
to take all object modules and link them together, resolving 
references between modules, and incorporating modules from 
referenced system libraries. The Task Builder outputs an 
executable task image. An optional output file is a map file that 
contains information describing the allocation of addresses, 
program sections in task image, modules of origin, and the values 
of all global symbols. A symbol definition file is other optional 
output that contains information used to create a Shared region. 
Shared regions and the use of the file are covered in another 
course. 


Before releasing a task for general use, the task should be 
run and tested against original specifications to ensure that it 
does indeed run correctly and solves the original problem ( 4 in 
Figure 5-1). Debugging aids, like the On-Line Debugging Tool 
(ODT), can be used to help locate problems within the _ code. If 
any error conditions arise during this step it may be necessary to 
go back to the first step in the flowchart and repeat the steps 
once again until the task executes correctly. 


When the task is ready for general use ( 5 in Figure 5-1), it 
can be permanently installed in the System Task Directory. Not 
all tasks are permanently installed. Your system manager makes 
this choice based upon how often a task is run and how critical 
its nature. 
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START 
SOURCE 


i) FILE (.MAC) 


TEXT (.FTN) Sa 
EDITOR (EDT) i? CREATING AND 


FORMATTING 
ae ene MACRO-11 
LIBRARY FILE saad 
LISTING (DEFAULT=RSXMAC.SML) | FILES 
LANGUAGE FILE (.LST) 
r) PROCESSOR ASSEMBLING 
(FOR) CORRECTING 
A PROGRAM 
CORRECT OBJECT MODULE 
SOURCE FILE 
FILE YES ASSEMBLY (.OBJ) _ SRE 
ERRORS? LIBRARY FILE 
(DEFAULT=SYSLIB.OLB) 
MAP a. 
FILE (.MAP) 
TASK 
BUILDER BUILDING 
(TKB) AND 
— TESTING A 
SYMBOL DEFINITION TASK 
FILE (.STB) 
TKB 
APPLY SOURCE ERRORS? oe 
CORRECTIONS TASK IMAGE 
AS NEEDED FILE (.TSK) 
DUMP 
FILE (.PMD) <a RUNNING 
(4) RUN AND IN UFD [1,4] AND 
DEBUG DEBUGGING 
A TASK 


ERRORS? 


NO 
° 
IN STD 


TK-7671 


Figure 5-1 The Program Development Process 
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PROGRAMMING LANGUAGES 


There are three fundamental types of programming languages in 
use today; the difference is in the manner in which the 
translation of source statements into machine instructions occurs. 
These three types are interpreted, assembled and compiled 
languages. 


In an interpreted language, such as _ BASIC, each’ source 
Statement is translated and executed before the next line is read. 
There are no Separate compile or task-build steps. The results of 
arithmetic expressions and input/output statements are immediate 
and can be checked for correctness. As there iS no permanent 
output from the translation process, the cost of translating the 
source statements into machine instructions is borne each time the 
program is- run. An interpreted language is most often used for 
applications that are run infrequently but need to be developed 
quickly. They are also used as an instructional language for 
beginning programmers. 


In an assembled language, a program called an assembler 
translates source statements into machine instructions, which are 
saved in a file called an object file. Each source statement 
translates directly into one machine instruction. This 
intermediate file (called the object file) passes through another 
process, called linking, to make an executable image. Translation 
of source statements into machine instructions is not required 
each time the program is run. Therefore, execution time is less 
with an assembled language than an interpreted language. 


A compiled language, often referred to as a high-level 
language, processes like the assembled language. However, the 
Source Statements are more English-like, and each Source statement 
translates into one or more machine instructions. The program 
that converts high-level source code into object code is called a 
compiler. . 


Table 5-1 compares the three types of languages. 
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Table 5-1 Language Types 


os 


ee 


Be 
nee 
: 


Le, 
es 


Pee E 
ee 


227 


PROGRAM DEVELOPMENT 


Table 5-2 Available Language Translators for RSX Use 


oe 
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LEARNING ACTIVITIES 


READ Chapter 4, How to Do Work on_ the 
System, in the Introduction to 


RSX-11M/M-PLUS Manual. 


DO Written Exercises 1 through 6 for this 
module. 
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ASSEMBLING/COMPILING 


Figure 5-2 illustrates the process of translating a source 
file into machine instructions. Although a MACRO-11 program is 
used aS an example, the process is similiar for a compiled 
language. The reference numbers in the following text refer to 
the numbers on the figure. 


The language translator performs the following functions: 


@ Identifies symbols to be known to other modules (global 
symbols). 


Inserts macro definitions in MACRO-11 programs. 


Translates source language instructions’ into machine 
instructions. 


Assigns program addresses (relocatable virtual addresses) 
to each machine instruction. 


Input to the language translator consists of one or more 
modules written in the source language (item @). In the case of 
MACRO-11, input may also come from macro definition libraries 
(item @). The MACRO-11 assembler automatically searches 
RSXMAC.SML for any undefined symbols that remain after processing 
all the input files. 


Output from the language translator consists of an object 
module file and an optional listing file. The object file (item 
Q ) has a default file type of .OBJ, and contains the machine 
instructions and information needed in the next step of the 
program development process. The listing file (item @)has a 
default file type of .LST and contains the following: 

- source instructions 

- machine instructions (item @) 

- relocatable virtual addresses (item @) 

- error messages 


- symbol listings 


- assemble/compile statistics 
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@ PGMO01.MAC 


AD80 


@ PGM01.0BJ 


#TEXT,RO 
MOV #BUFF,R1 


MOV #DOT,R2 
LOOP: MOVB (RO)+,(R1) 000026 
CMPB (R1)+,R2 000146 012700 000000’ 


LOOP 000152 012701 000026’ 


000156 012702 000056 
000162 112011 
000164 122102 
000166 001375 


SY: [305,303] 000001 


SY:[305,303] 


ct 


ae 
Ps) MAC.TSK Goat ae 
LANGUAGE | PGMOT.MAC_| 

LB:[1,1] PROCESSOR PGMO1.OBJ 
(MACRO-11) | PGMOT.LST 


ll 


PGMO1.LST 


cet(teN 
8 000026 r) BUFF:: .BLKB AD80 


11 000146 012700 000000'ST: MOV #TEXT,RO 
12 000152 012701 000026’ MOV #BUFF,R1 
13 000156 012702 000056 MOV #DOT,R2 
14 000162 112011 LOOP: MOVB (RO)+,(R1) 
15 000164 122102 CMPB (R1)+,(R2) 
16 000166 001375 BNE LOOP 


000001 


TK-7673 


Figure 5-2 Translating a Program Source File Into Machine Language 


231 


PROGRAM DEVELOPMENT 


MACRO-11 Language 


The command format below shows how to invoke the MACRO-11 
Assembler. The MACRO-11 Assembler takes MACRO source files and 
library files as input. The default input file type is .MAC. In 
specifying a series of input files, the last file specified cannot 
be a library file. You should place a library specification in 
front of the source file that requires it. After processing all 
the input files, the MACRO Assembler automatically searches’ the 
system macro library, RSXMAC.SML, for unsatisfied macro 
definitions. The last file name in the command is used as_ the 
default’ name for the output files. Table 5-3 lists some of the 
more frequently used command qualifiers. For more qualifiers, 
refer to Chapter 6 of the RSX-11M/M-PLUS Command Language Manual. 
Table 5-4 shows some examples of MACRO command usage. 


MACRO-11 Assembler Command Format 


>MAGCRO/LIST USER/ LIBRARY, PROG 


wee ee ee 


Command name 
Command qualifier 
Input file specification (default file type = .MAC) 


Input file specification delimiter 


Input file specification qualifier 
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Table 5-3 MACRO Command and File Qualifiers 


o 
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Table 5-4 
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Common Error Messages 


8-14 
description of 


MAC 


MAC 


MAC 


MAC 


MAC 


MAC 


MAC 


MAC 


The following are common MACRO-11 error messages. 
through 8-17 of the MACRO-11 Reference Manual 
these and other error messages. 


COMMAND SYNTAX ERROR 


ILLEGAL FILENAME 


ILLEGAL SWITCH 


I/O ERROR ON 
I/O ERROR ON 
I/O ERROR ON 
OPEN FAILURE 


OPEN FAILURE 


INPUT FILE 


MACRO LIBRARY FILE 


OUTPUT FILE 


ON INPUT FILE 


ON OUTPUT FILE 
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Notes on Example 5-1 


Example 5-1 shows a section of a MACRO-11 listing file. The 
following comments are keyed to the example. 


eo 0 


The title of the program 

Assembly instructions that control the type of output. 
These may be overridden at assembly time by using the 
appropriate MACRO command qualifier. 


Source line numbers. Diagnostic messages refer to these 
numbers. 


Virtual addresses assigned to the machine instruction 

The resulting machine instruction 

The MACRO-11 source instruction 

Comments to explain the logic of the program 

A table of all symbols defined and/or referenced in the 
file. Asterisks in the address field denote unsatisfied 
references. Their definitions need to be satisfied at 
link time. Those symbols with an R following the address 
are relocatable addresses. Those symbols with a G are 
global symbols. A global symbol is one that may be 
referenced from another source file. 


Diagnostic Section 


Assembly statistics, including the assembly time and 
command line (in MCR format) that invokes the assembly. 
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HIYA MACRO M1200 91*DEC@81 15:22 PAGE 1 


© 1 TITLE HIYA 
2 wLIST TT 
3 °o »NLIST BEX 
4 
5 
6 3 MACRO LIBRARY CALLS 
; 
8 eMCALL EXITSS,QIOWS,DIRS 
9 
10 000000 INDPB: QIOWS IO.RLB,S,1,,10ST 3 REST TO BE FIL 
11 000030 QUTDPB: QIOWS IO.WLB,5,1,,10ST,,<,,40> 
12 
13 3 LOCAL EQUATES 
14 
15 000120 S8SIZE=80, ; ACCEPTS NAMES UP TO 80 
16 
17 
18 : LOCAL DATA BUFFERS 
19 
20 000060 103 MSGi: .ASCII /COULD I HAVE YOUR NAME PLEASE?/ 
21 000036 MSGIL=,=MSGi : THE LENGTH OF MSG1 
22 
23 000116 422 MSG2: .ASCIT /RSX*11M*PLUS CALLING / 
24 000025 MSG2L=.—MSG2 ’ THE LENGTH OF MSG2 
25 000143 BUFF:  .BLKB BSIZE 3} SFT UP BUFFER LENGTH = BSIZE 
26 
27 000263 111 OBUFF: .ASCIY /IO ERROR WITH STATUS/<12><15> 
28 090311 104 Ii: eASCII /DSW = / 
29 000326 111 12: eASCII /IOST = / 
30 000060 OSIZ=,-OBUFF 
31 
32 
33 wEVEN 
34 000344 IoSt: .BLKW 2 
35 
36 
37 
38 : MAIN PROGRAM 
39 oe 7 | 

4 | 40 000350 012700 HIYA: “MOV #™SG1,R0 3 SET UP CALL 
41 000354 012701 MOV #MSG1L,R4 ¢ TO WRITE SUBROUTINE 
42 000360 004767 CALL WRITE ; OUTPUT MSG1 
43 000364 012700 MOV #BUFF,RO } SET UP CALL 
44 000370 012701 MOV #BSIZE,R1 + TO READ SUBROUTINE 
45 000374 004767 CALL READ : READ NAME INTO BUFFER 
46 000400 012700 MOV #MSG2,RO 3 SET UP CALL 
47 000404 012701 MOV #MSG2L,R1 : TO WRITE SUBROUTINE 
48 000410 060201 ADD R2,R1 } LENGTH OF MSG2 + NAME 
49 000412 004767 CALL WRITE : OUTPUT MSG2 WITH NAME 
50 000416 EXIT$S } LEAVE 
51 i+ 
52 }; WRITE = SUBROUTINE TO WRITE A MESSAGE TO THE TERMINAL 
53 ; 
54 3 INPUTS: 
55 ; RO = ADDRESS OF STRING TO BE PRINTED ON SCREEN 
56 ; Ri - LENGTH OF STRING TO PRINT 
57 : 


Example 5-1 Sample MACRO Assembly Listing (Sheet 1 of 2) 
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HIYA MACRO M1200 O1*DEC#841 15:22 PAGE 1=3 
8) SYMBOL TABLE 
BSIZE = 000120 MSG1 000060R Q.IOLU= 000004 
BUFF 000143R MSG1L = 000036 Q,IOPL= 000014 
ERR1 000510R MSG2 000116R O.,IOPR= 000007 
HIYA 000350R MSG2L = 000025 Q,10SB8= 000010 
INDPB 000000R OBUFF 000263R READ 000454RG 
LOST 000344R OSIZ = 000060 WRITE 000424RG 
LO, RLB= *#*KKE CX OUTDPB 000030R SCBDSGS *¥#eKE GX 
IO .WUBS *#* eee Q.IOAE= 090012 SDSW = ¥REKEK CX 
tl 000341R Q,IOEF= 000006 $S$$ARG= 000003 
12 000326R Q.IOFN= 000002 $SSOST= 000014 
. ABS, 000000 000 
000574 001 
9) ERRORS DETECTED: 0 
© VIRTUAL MEMORY USED: 8774 WORDS (¢ 35 PAGES) 


DYNAMIC MEMORYs 10316 WORDS ( 39 PAGES) 
ELAPSED TIMFs: 00:00:306 


HIYAL,HIYAL=SHIYA1 


Example 5-1 Sample MACRO Assembly Listing (Sheet 2 of 2) 


LEARNING ACTIVITIES 


l. READ the following sections in the 
RSX-11M/M-PLUS Command Language Manual: 
@e 6.1, Introduction 
e 6.2, Source Language 
2. DO Written Exercises 7 through 18 for 


this module. 
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FORTRAN Languages 


RSX-l11M/M-PLUS systems support three FORTRAN source’ language 
compilers: FORTRAN IV, FORTRAN IV-PLUS and FORTRAN-77. Check 
with your system manager to determine which compiler (if any) your 
system has. Input source file(s) must contain Source statements 
that comply with the rules of the compiler that you plan to uSe. 


The command format below shows how to invoke a _ FORTRAN 
compiler. If you wish to use the FORTRAN IV-PLUS or FORTRAN-77 
compiler, you must use the appropriate command qualifier to 
specify which one (Table 5-5). FORTRAN IV is the default FORTRAN 
compiler. The default input file type is .FTN for all_ three 
compilers. Output from the FORTRAN compiler can be an object file 
and/or a listing file. 


Table 5-6 gives examples of how to construct a command. to 


compile a FORTRAN source file called PROG.FTN, as well as the 
equivalent MCR commands. 


FORTRAN Compiler Command Format 


>FORTRAN/F4P CALCA,SINEX,SINEY 


Command name 
Command qualifiers 


File specification (default file type = .FTN) 


File specification delimiter 
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Common FORTRAN Error Messages 


The following are common FORTRAN error messages. 


See 


Appendix C in the FORTRAN IV User's Guide for a complete 


description of all error messages. 
FOR -- BAD SWITCH 


FOR -- BAD SWITCH VALUE 


FOR -- ERROR READING SOURCE FILE 
FOR -- ERROR WRITING LISTING FILE 
FOR -- ERROR WRITING OBJECT FILE 
FOR -- OPEN FAILED FOR FILE 

FOR -- SYNTAX ERROR 

FOR -- TOO MANY INPUT FILES 

FOR -- TOO MANY OUTPUT FILES 

FOR -- WILD CARD NOT ALLOWED 


FORTRAN Compiler Listing 


Example 5-2 is a sample of a FORTRAN compiler listing. 
listing file is optional compiler output. To generate the 
the /LIST qualifier must be specified in the FORTRAN command 
The default file type is .LST. The following comments are 
to the example. 


@ compiler name and version number, time and da 


compile, and the compiler command (in MCR) invoki 
compilation. 


these numbers. 
FORTRAN Source statements. 


Diagnostics indicating problem areas in the code. 


Storage map providing information on _ symbols, 
blocks, arrays, and Subroutines. 
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@ rortran iv v02.21 TUE 0}*DEC*81 15251232 PAGE 001 
PROG, PROG=PROG 

© 0001 © conmonsconsi(10) 
0002 DO 100, J=1,10 
0003 READ(5,900)1(J) 
0004 CALL SUB(J,M) 
0005 WRITE(5, 901) 
0006 100 CONTINUE 
0007 WRITE(5,902) 
0008 CALL EXIT 
9009 SUBROUTINE SUBCU,K) 
0010 COMMON/COM/1(10) 
0014 K=2¥*1(J) 
0012 RETURN 


0043 900 FORMATCI3) 

0014 901 FORMAT(’ °,16) 

0015 902 FORMAT(’ THIS IS THE END’) 
0016 END 


© rortRAN Iv DIAGNOSTICS FOR PROGRAM UNIT .MAIN, 
IN LINE 0002, WARNING: POSSIBLE MODIFICATION OF INDEX "J" 


IN LINE 0009, ERROR? SUBPROGRAM STATEMENT MUST BE FIRST 
IN LINE 0010, ERROR: MULTIPLE DECLARATION FOR VARIABLE "I" 


6 FORTRAN IV STORAGE YAP FOR PROGRAM UNIT «MAIN, 


LOCAL VARIABLES, .PSECT SDATA, SIZE = 000006 (¢ 3. WORDS) 
NAME TYPE OFFSET NAME TYPE OFFSET NAME TYPE OFFSET 
J I¥*2 000000 K I*2 000004 M I*2 900002 


COMMON BLOCK /COM 4, SIZE = 000024 ¢ 10, WORDS) 


NAME TYPE OFFSET NAME TYPE OFFSET NAME TYPE OFFSET 
I I¥*2 0090000 


LOCAL AND COMMON ARRAYS: 


NAME TYPE SECTION OFFSET swwee"SIZEswe== DIMENSIONS 
T I*2 COM 900000 000024 ¢ 10.) (10) 


SUBROUTINES, FUNCTIONS, STATEMENT AND PROCESSOR@DEFINED FUNCTIONS? 


NAME TYPE NAME TYPE NAME TYPE NAME TYPE NAME TYPE 
EXIT R¥*4 SUB R*4 


Example 5-2 Sample FORTRAN Compiler Listing 


243 


aa 


2% 


PROGRAM DEVELOPMENT 


LEARNING ACTIVITIES 


READ Section 6.2.3, FORTRAN, in the 
RSX-11M/M-PLUS Command Language Manual. 


DO Written Exercises 11 through 15 for 
this module. 
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Overview 


Figure 5-3 illustrates the next step in the program 
development process, linking object modules into an executable 
task image. This step is called task-building or linking. A 
special system utility, the Task Builder, performs this function. 


Generally, a task image will be built using many object 
modules that may reside in more than one object file. In an 
object module, a reference can be made to a symbol or routine 
located in another object module. The symbol or routine can also 
be located in a special file called an object library. It is’ the 
Task Builder's function to bring together all the object modules 
from object files and libraries, and join them together logically 
into one output file called the task image file (item @ in Figure 
5-3). The Task Builder also resolves references to symbols’ and 
routines in different modules by placing the appropriate address 
in the instruction where the reference was made. In this way, all 
the separate modules that make up a task are linked together. 


Input to the Task Builder (item ©) are the object files that 
are output from the assembler or a compiler. The default input 
file type is .OBJ. Another source of input is user or_ system 
object libraries. These libraries contain code for frequently 
used routines that have been developed and debugged. If after 
processing all the input files there remain symbols that have not 
been defined, the Task Builder automatically searches the system 
library looking for the code. This library, SYSLIB.OLB, is 
located in LB:[1,1] (item ©). If the search is successful, the 
Task Builder includes in the task the object module from the 
library. 


Task Builder output can include a task image file, a map 
file, and a symbol definition file. Each output file is optional, 
and the Task Builder will generate any combination of the’ three. 
The task image file (item @) contains the actual machine 
instructions that load into memory and execute in the CPU. The 
Task Builder creates the file in the special format shown in 
Figure 5-4. (See the notes that refer to this figure.) 


Another output file of the Task Builder, and a useful tool 
for the programmer, is the MAP file (item @)- This file 
contains information on the allocation of address space in the 
task image, the program sections created in the task image, and 
the module of origin and the value of each global symbol. We will 
discuss this file in more detail later. 
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The symbol table file is the third output file (item @). 
This file contains global symbols defined in the task, and their 
virtual or relocatable addresses. It is in a format suitable for 
reprocessing by the Task Builder. You specify this file when you 
are building a resident library or common. Resident libraries and 
commons are discussed in the Task Builder Manual, and are advanced 
topics covered in the RSX-11M/M-PLUS Programmer course. They will 
not be discussed here. 


Table 5-9 lists some of the characteristics of a task that 
the operating system must know before the task can be run. These 
characteristics, supplied at task-build time, are included in the 
label and header portions of the task image. If these are not 
specified, the task is built with the default values listed in the 
table. In Module §8,. we discuss building a task with different 
characteristics. 
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SY: [305,303] 


PGM01.0BJ 
RTNO1.OBJ 
RTNO2.0BJ 


LB:[1,1] 3 


SYSLIB.OLB 


Figure 5-3 
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PGM01.TSK 


LABEL BLOCK 
HEADER 


STACK 


PGMO1 
CALL RTNO1 
CALL RTNO2 


SY: [305,303] 


4 
TASKBUILDER 5 P pewormar | 
° PGMO1.STB 


PGM01.MAP 


OVR.TSK;25 MEMORY ALLOCATION MAP TKB M36 


13-APR-79 09:10 


TASK NAME 

PARTITION NAME > GEN 

IDENTIFICATION : 01 

TASK UIC : [303,3] 

TASK PRIORITY : 

STACK LIMITS : 000176 001175 001000 00512. 


ODT XFR ADDRESS 

PRG XRF ADDRESS : 010010 
TASK ATTRIBUTES : 

TOTAL ADDRESS WINDOWS : 1. 
MAPPED ARRAY 

TASK EXTENSION 


TASK IMAGE SIZE : 10496. WORDS 
TOTAL TASK SIZE : 
TASK ADDRESS LIMITS : 000000 050753 


R-W DISK BLK LIMITS : 000002 000106 000105 00069. 
R-O DISK BLK LIMITS : 


OVR.TSK;25 OVERLAY DESCRIPTION: 


BASE TOP LENGTH 


000000 020677 020700 08640. ROOTM 
020700 034723 014024 06164. MULOV 
020700 034723 014024 06164. ADDOV 
034724 050747 014024 06164. SUBOV 
034724 050753 014030 06168. DIVOV 


OVR.TSK;25 MEMORY ALLOCATION MAP TKB M36 
ROOTM 13-APR-79 09:10 


TK-7674 ° 


Task-Building an Executable Module 
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1000 
750 


500 
RTNO2.OBJ 
PGM01.0BJ RTNO1.0BJ 


0 0 0 


OBJECT MODULES SUPPLIED 
IN THE TASKBUILD 


RTNO2.OBJ 
-RTNO1.0BJ 
PGMO01.OBJ 


STACK 
HEADER 
LABEL BLOCK 


PGMO1.TSK 


X+1500 


X+1000 


TK-7677 


Figure 5-4 Task Image Structure 
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Notes on Figure 5-4 


The following comments are keyed to the figure. 


Label Block 


Contains task information necessary for running the task 
(name, partition, size, priority). The INSTALL command 
uses this information to create a Task Control Block (TCB) 
in the STD, and to initialize the task header. 


Header 


Contains information the Executive uses to run the task. 
Also provides a storage area for saving essential data 
when the task is  checkpointed. The INSTALL command 
initializes the part of the header not initialized by the 
Task Builder. 


Stack, Code and Data 
This part of the task image includes the task stack and 
linked modules of code and data. The task header along 


with the stack, code and data are loaded into memory when 
a task is requested to run. 
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Task Builder Command Format 


The command format below shows the baSic structure used_ to 
invoke the Task Builder. Input to the Task Builder consists of 
object files and library files. The default input file type for 
object modules is .OBJ. Library file specifications must include 
the /LIBRARY qualifier, and are of default type .OLB. The default 
output file types include .TSK for the task image file, .MAP for 
the map file, and .STB for the symbol table file. 


The LINK command can take qualifiers that modify the linking 
of modules. The most frequently used qualifiers are listed in 


Table 5-7. The RSX-11M/M-PLUS Command Language Manual describes 
these and others in more detail. Examples of the LINK command and 


equivalent MCR commands are Shown in Table 5-8. 


>LINK/MAP ROOT,RTN1,USOBJ/LIB 


Command name 
Command qualifier 
Input file specification 


File specification delimiter 


File specification qualifier 
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Table 5-7 LINK Command and File Qualifiers 
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Table 5-9 Standard Task Builder Defaults 
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Common Task Builder Error Messages 


The following is a list of common Task Builder error 


messages. See Appendix F of the Task Builder Manual for a 
complete description of all error messages. 


ALLOCATION FAILURE ON FILE file-name 
COMMAND SYNTAX ERROR 

FILE file-name HAS ILLEGAL FORMAT 
ILLEGAL FILENAME 

INVALID PARTITION/COMMON BLOCK SPECIFIED 
I/O ERROR ON INPUT FILE file-name 

I/O ERROR ON OUTPUT FILE file-name 
LOOKUP FAILURE ON FILE file-name 

OPEN FAILURE ON FILE file-name 

REQUIRED INPUT MISSING 

TASK IMAGE FILE file-name IS NONCONTIGUOUS 


n UNDEFINED SYMBOLS SEGMENT seg-name 
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Interpreting a Task Map 


Example 5-3 is a sample of the Task Builder map file. It 
tells which modules were used to build the task, in what order 
they were linked together, and at what virtual address they begin. 
It also gives other information that is useful when debugging a 
program. Read the notes for more details on the example. For 
further information, refer to the discussion of the /SH switch in 
Chapter 18 of the Task Builder Manual. Not all of this 
information is of value to you now. It is important, however, 
that you know what the map file is and what type of information it 
contains. 


HIYA1,.TSK Memory allocation map TKB M39,7D Page 1 
1“DEC=81 15323 


Partition name : GEN @ 

Identification : 0351 

Task UIC : (305,3031@ 

Stack Limits: 000254 001253 001000 00512.@ 
PRG xfr address: 001624 @ 

Total address windows: 1, 

Task image size : 640, words@ 

Task address limits: 000000 00237790 

RoW disk blk limits: 000002 000004 000003 00003, 


#** Root segment: HIYA1@ 


R/W mem limits: 000000 002377 002400 01280, @ 
Disk blk limits: 000002 000004 900003 00003, 


Memory allocation synopsis: 


Section ° Title Ident File 
. BLK.:(RW,I,LCL,REL,CON) 001254 001012 00522. 

001254 000574 00380, HIYA HIYA1,0B071 @ 
$8RESL3(RO,I,LCL,REL,CON) 002266 000112 00074, 


Global symbols: 


READ 001730°R WRITE 0017008R 


*** Task builder statistics: 


Total work file references: 1099. 

Work file reads: 0, 

Work file writess 0, 

Size of core pool: 7086. words (27, pages) 
Size of work file: 1024, words (4, pages) 


Elapsed time:00:00:03 


Example 5-3 Sample Task Map 
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Notes on Example 5-3 


The partition in which the task will be loaded. 


The UIC under which the task will be run for time-based 
schedule requests. This determines which files the task 
can access. 


The low and high limits of the task stack, followed by its 
length in octal and decimal bytes. 


The virtual address at which the program will begin 
executing. 


The task image size in decimal words. 


The lowest and highest virtual address allocated to’ the 
task. 


The name of the root segment, in this case, the task name. 
From left to right: 


Beginning virtual address of root segment 
Virtual address of the last segment byte 
Length in octal bytes 

Length in decimal bytes 


From left to right: 


Program Section name 

Program section attributes 

Starting virtual address of the section 
Length in octal bytes 

Length in decimal bytes 


This line contains the same first fields as 9 and alSo a 
title and identification number obtained from the source 
code, and the name of the file containing the source code. 


This section contains Statistics that are of no interest 
to the general user. 
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LEARNING ACTIVITIES 


READ the following sections in the 
RSX-11M/M-PLUS Command Language Manual: 


e 6.4, Linking the Task 


e 6.4.1, Introduction to the Link © 
Command 


e 6.4.2, Link 


DO Written Exercises 16 through 19 for 
this module. 
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RUNNING THE TASK 

After linking, you run a task by supplying the task image 
file specification aS a parameter to the RUN command. The 
operating system will then go through the procedure of installing, 
running and removing your task, as shown in Figure 5-5. This is 
the most frequently used version of the RUN command, as most tasks 
are not permanently installed in the STD. We will discuss the 


other versions of the RUN command in Module 8, Controlling Task 
Execution. 


LEARNING ACTIVITIES 


1. READ the following sections in the 
RSX-11M/M-PLUS Command Language Manual: 


e 7.1, Task Installation and Execution 
e 7.1.1, Task Naming 
e 7.2, Introduction to the RUN Command 
e 7.3, Abort Command 


2. DO Written Exercises 2@ and 21 for this 
module. 


3. DO the Lab Exercises for this module. 
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MEMORY 


1/0 PAGE 
DRVPAR 


XYZPAR 


SY: [305,303] 


> RUN PGMo1 @ 


TK-7678 


Figure 5-5 Requesting a Task to Run 


Notes on Figure 5-5 
The following comments are keyed to the figure. 
1] User requests PGM@1 to run 
@ PGMg1 added to the list of known tasks 
@ PGMG1 added to the lists of active tasks 
@ PGM#1 loaded into aenoEy ready-to-run 


On completion, entries in STD and ATL for PGM@1 are removed. 
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USING THE EDITOR EFFECTIVELY 


INTRODUCTION 


EDT, the DEC editor, creates and modifies files. As you grow 
more accustomed to using it, you will appreciate many additional 
features that make it quicker to use. A number of these 
additional features is presented in this module. 


OBJECTIVES 


1. Move or copy sections of text from one buffer to another. 
2. Read in text from another file. 

3. Write a subset of the text to an output file. 

4. Write a Macro to execute EDT commands. 

5. Set editor characteristics for special purposes. 


6. Use character mode with a keypad. 


RESOURCES 


1. EDT Editor Manual 
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USING THE EDITOR EFFECTIVELY 


There are many features of the editor that will make your 
editing sessions easier. Such features as alternate buffers, 
user-defined macros, and the ability to set terminal 
characteristics, do character searches, and perform cut and paste 
operations can shorten the time it would normally take to create a 
file. Suppose, for example, that you had the responsibility of 
writing a user's manual for a piece of hardware. After capturing 
your first thoughts using the editor, you decide to order the 
Paragraphs differently. The cut and paste feature of character 
mode allows you to select a paragraph, phrase or word and easily 
move it to another location. You can guess how long an editing 
session would be if you had to delete the lines and retype them in 
their new location! This is one of many features discussed in 
this module that will make your editing session easier. 


Editor Buffers 

From our previous discussion on the editor, you learned that 
the editor creates workspaces called buffers. At the start of an 
editing session, EDT automatically creates two standard buffers 
for use during the editing session. The first buffer, called 
MAIN, is for general editing. The second buffer, called PASTE, is 
for the cut and paste operations done in character mode. 


EDT also allows for the creation of additional buffers as 
they are needed. 


Buffer Use 
You may use these buffers in the following ways: 
e To divide one or more files into sections 
e To include part or all of another file 


e To create another file from part or all of the text in a 
buffer 
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Creating a Buffer 


You create a buffer by naming it, i.e., by referencing a 1-39 
character name preceded by an equal sign. (See example below.) 
You can make the reference on a line by itself, or in a range 
specification. The reference automatically creates the buffer and 


places your cursor at the beginning of the buffer. For example, 
issuing the command =NEWBUF alone on a line creates a buffer with 
the name NEWBUF. This becomes your current buffer, and_ the 


current line is now pointing to the beginning of the buffer. You 
can also create a buffer while performing editor operations such 
as MOVE or COPY. For example, you may reference a buffer name in 
a range specification in the COPY command. EDT will first create 
the buffer and then copy the lines into the buffer. Once again, 
the buffer is now the current buffer and the current line is in 
the new buffer, not MAIN. 


Example: *=NEWBUF 


Referring to a Buffer 


Part of a range specification is the buffer name. If you do 
not supply a buffer name ina range specification, the editor 
assumes you are referring to the current buffer. If you wish to 
specify another buffer, it is done this way: 


*MOVE 1:3 TO =DOC 5 


This example moves lines numbered 1 through 3 from the current 
buffer to the line before line number 5 in the buffer named DOC. 


You determine the current buffer by using the SHOW BUFFER 
command: 


*SHOW BUFFER 

=NEWBUF 2@ LINES 
MAIN 269 LINES 
PASTE @ LINES 


The buffer preceded by the equal sign is the current buffer. 
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LINE MODE FEATURES 


Searching for a Character String 


The line mode search function is useful for locating a _ word 
or character string when the line number of the string location is 
not known. The search direction can be either forward or backward 
from the current line position. It is also possible to search for 
all occurrences of a string within a range of lines, or _ through 
the complete file. 


When you encloSe a character string with single or double 
quotes and type a carriage return, the editor searches forward in 
the file to locate the first occurrence of the string. Table 6-1 
lists the formats for this and other types of character searches. 


Table 6-1 String Search Commands in Line Mode 


Reading and Writing Files 


The editor has additional file-handling facilities to aid the 
user during the editing session. You will find the INCLUDE 
command useful when you want to include the contentS of another 
file in the one you are creating. This is done by specifying 
INCLUDE with the name of the file to be included, and giving a 
range specification to indicate where it is to be placed in the 
new file. One use of this command is to include a file in an 
alternate buffer, and search the alternate buffer for specific 
lines of text. Once located, the lines can be copied into’ the 
correct poSition in the MAIN buffer. There is no need to clean up 


the alternate buffer as the exit command saves only the contents 
of MAIN. 
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The WRITE command will create a file containing all or part 
of the text that you are editing. Once the file is created you 
may continue work in the editing session. The /SEQUENCE qualifier 
of the WRITE command allows you to save the editing line numbers 
along with the text. These line numbers will not be displayed 
when you type the file to the terminal, but will appear when you 
print the file on a line printer. WRITE is also useful when you 
wish to break up a file into many files. Suppose you have a 
FORTRAN source file containing many Subroutines. You can divide 
that file into one file per subroutine by issuing the WRITE 


command the appropriate number of times with the appropriate range 
specifications. 


The PRINT command allows you to create and print files in one 
operation. When you issue this command with a file name and range 
specification, the editor will create a file containing the lines 
of text specified, and then automatically print the file for you. 


Table 6-2 lists examples of the commands used for each of 
these features. 


Table 6-2 Line Mode Commands to Read and Write 
Files from Within EDT 


Generating EDT Macros 
A Macro 


The DEFINE MACRO command is another useful EDT feature. 
Before we discuss the command, we need to define the term macro in 
relation to the editor. A macro is a sequence of editing commands 
with a name asSigned to it. You can issue the macro name just 
like a line mode command. Every time you do so _ the- editor 
executes the sequence of commands. This facility allows you to 
extend the range of commands available for your use in EDT. 


266 


USING THE EDITOR EFFECTIVELY 


Defining a Macro 


DEFINE MACRO establishes the sequences of commands to a macro 
name. When you issue this command, the editor sets up a buffer 
with the name you supply in the DEFINE MACRO command. Using the 
INSERT command, you can enter the EDT commands of your choice into 
the buffer. This macro name then becomes a part of the_ EDT 
command list for the duration of the editing session, and can be 
used just like any other command. It can also be used in 
character mode by using the GOLD COMMAND function. If you want to 


save this macro for use during future editing sessions, perform 
the following steps: 


1. Use WRITE to put the contents of the macro buffer into a 
file. 


2. In your next editing session, use DEFINE MACRO again to 
set up the buffer. 


3. Then use INCLUDE to read the file created above into’ the 
buffer created by DEFINE MACRO. 
Notes on Example 6-1 


Example 6-1 shows the process of creating and executing a 
macro in line mode. The following notes are keyed to the example. 


@ command to define the macro. The name of the macro is 
DOC. 


SHOW BUFFER command issued to show all existing buffers. 


Command to make DOC the current buffer so that text is 
stored in it, not MAIN. 


Enter input mode and type the editor commands. 


Set the current buffer back to MAIN (which is empty at 
this time). 


Execute the macro. 
Display the contents of MAIN. 
Execute the macro again. | 


Display the contents of MAIN again. 


69000000 0 


Save the macro DOC in a file called DOC.MAC. 
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~“EDIT/EDT MANUAL. TXT 
Input file does not exist 


CEOBI 
*XHEFINE MACRO LOC 
XSH BUF 
noc 0 lines 
=MAIN 0 lines 
PASTE 0 lines 
*=HOc 
CEQBI 
xI 
INSERT Es sCHAF TER 
INSERT E33 
INSERT £5 sSECTION 
INSERT E33 
INSERT E533 
“Z 
CEOB 
x=MAIN 
CEOR] 
*xDoc 
*=MAIN 
1 sCHAF TER 
2 3 
3 sSECTION 
4 ; 
5 3 
CEORI 
*DOC: ; 
*=MAIN 
1 s CHAPTER 
2 3 
3 +SECTION 
4 ; 
5 ; 
é # CHAPTER 
7 3 
8 +SECTION 
9 3 
10 ; 
CEORI 


XWRITE DOC.MAC =DOC 
DRO{C305»303ID0C.MAC#1 5S lines 


KEXIT 
DRO{L3OS»SOSIMANUAL.TXT#1 15 lines 


Example 6-1 Defining a Macro 
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Setting Editor Parameters 


There are many operating characteristics of EDT that you’ can 
set for an editing session. These characteristics control how 


information is displayed at your terminal. The SET and SHOW 
commands allow you to alter the default characteristics, or to 


display their settings. Table 6-3 lists some parameters you may 
find useful. Table 6-4 summarizes other useful line mode 


commands. 


Table 6-3 SET and SHOW Commands 
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Additional Line Mode Commands 
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The Startup Command File 


When you start your editing Session, EDT automatically 
Searches your UFD for a file called EDTINI.EDT. This file, if it 
exists, is then read by EDT for commands that would customize the 
editing session. If this file does not exist, EDT initializes the 
editing session in the standard way. 


You create this file, called a startup command file, using an 
editor. It contains line mode commands that you want to have 
executed automatically when EDT is started. Such commands as SET, 
DEFINE MACRO, DEFINE KEY and INCLUDE may be used to create your 
own editing environment. By uSing SET MODE CHANGE in the _ file, 
EDT will automatically change to character mode every time you 
Start the editor. The process of using an existing EDT macro 
discussed before in the section, Defining a Macro, can be done 
automatically by putting the DEFINE MACRO and INCLUDE commands in 
the startup command file. Then each time you use the editor, the 
macro would be available without your having to recreate it. 


If you have an EDTINI.EDT file in your UFD and wish to edit a 
file without first initializing EDT, use the /NOCOMMAND qualifier 


Shown below. EDT will start up normally without reading the start 
up command file. 


EDIT/EDT/NOCOMMAND filespec 
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CHARACTER MODE FEATURES 


Tables 6-5 and 6-6 Summarize some of the available features 
of the character mode. 


Additional Keypad Functions 
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LEARNING ACTIVITIES 


1. READ the following in the EDT Editor 
Manual: 


e Chapter 6, Line Numbers, Text Buffers 
and Ranges 


- Section on Text Buffers 
e Chapter 9, Set and Show Commands 
e Chapter 7, Line Editing 


- Sections on Clear, Define Key, 


Replace and Substitute Next, 
Define Macro 


e Chapter 4, The Command Line and 
Startup Command Files 


2. DO Lab Exercises 1 through 18 for this 
module. 7 
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Other Character Mode Functions 


Additional Character Mode Fun 
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String Searches in Character Mode 


Character mode also has string search capability. This is 
done by the following procedure: 


1. Position the cursor at one end of a range of lines to be 
searched. 


2. User types: ADVANCE/BOTTOM ) or{(BACKUP/TOP)to establish 


the direction of the search 


3. User types: GOLD)(FINDNEXT/FIND 


4. EDT responds: SEARCH FOR: 


5. User types: THIS IS ENTER/SUBS 


The string is remembered, and additional searches can be done 
using the FINDNEXT key: 


1. User types: FINDNEXT/FIND 


Cutting and Pasting Text 


Cutting and pasting text in character mode is equivalent to 
the copy command in line mode. However, because you are in 
character mode, you can select a section of text that begins in 
the middle of a line, and move it to a location in the middle of 
another line. The text you select is Stored in the PASTE buffer; 
more text can be appended to this buffer using the APPEND 


function. The following procedure shows how to use the CUT and 
PASTE feature: 


l. Move the cursor to one end of the portion of text to be 
moved. 


2. Type SELECT/RESET 


3. Move the cursor to the other end of the portion of text to 
be moved. | 


4. Type CUT/PASTE). The text is now saved in the PASTE 
buffer. 


5. Move the cursor to the deSired new location. 


6. Type GOLD CUT/PASTE 
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Repeating Functions Automatically 


Many times, you would like to delete more than one 
consecutive word or character at a time. You can do this by 
typing the DEL L or DEL W key an appropriate number of times, but 
there is another way that requires fewer key strokes. Suppose you 
want to delete the next five words. After ensuring that’ the 
ADVANCE direction is set, you type the sequence of keys shown in 
the example. Note that the 5 key is the one on the_- standard 
keyboard and not the one on the keypad. The 5 on the keypad 
already has a special meaning, other than the number 5. 


Example: 


Keys : GOLD 5 DEL WORD 


Before Command: 


LL A MAN THERE ARE 300 BILLION STARS IN THE UNIVERSE 
D KHE°’LL BELIEVE YOU. TELL HIM A BENCH HAS WET PAINT 
ON IT AND HE‘LL HAVE TO TOUCH IT TO BE SURE, 


UNDER THE MOST RIGOROUSLY CONTROLLED CONDITIONS OF PRESSURE 
TEMPERATURE, VOLUME, HUMIDITY, AND OTHER VARIABLES THE 
ORGANISM WILL DO AS IT DARN WELL PLEASES, 


ANY GIVEN PROGRAM, WHEN RUNNING IS OBSOLETE, 


THE ATTENTION SPAN OF A COMPUTER IS ONLY AS 
LONG AS ITS ELECTRICAL CORD. 


THE DEGREE OF TECHNICAL COMPETENCE IS INVERSELY PROPORTIONAL 
TO THE LEVEL OF MANAGEMENT, 


A FAILURE WILL NOT-APPEAR TILL A UNIT HAS PASSED 
FINAL INSPECTION, 


After Command: 


'J00 BILLION STARS IN THE UNIVERSE 
AND HE’LL BELIEVE YOU... TELL HIM A BENCH HAS WET PAINT 
ON IT AND HE’LL HAVE TO TOUCH IT TO BE SURE, 


UNDER THE MOST RIGOROUSLY CONTROLLED CONDITIONS OF PRESSURE 
TEMPERATURE, VOLUME, HUMIDITY, AND OTHER VARIABLES THE 
ORGANISM WILL DO AS IT DARN WELL PLEASES, 

ANY GIVEN PROGRAM, WHEN RUNNING IS OBSOLETE, 


THE ATTENTION SPAN OF A COMPUTER IS ONLY AS 
LONG AS ITS ELECTRICAL CORD, 


THE DEGREE OF TECHNICAL COMPETENCE IS INVERSELY PROPORTIONAL 
TO THE LEVEL OF MANAGEMENT, 


A FAILURE WILL NOT APPEAR TILL A UNIT HAS PASSED 
FINAL INSPECTION, 


TK-7875 
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Entering Line Mode Commands 


In addition to the character mode commands, line mode 
commands are alSo available from within character mode. The 
following are examples using two line mode commands in character 
mode: 


e SET NOTRUNCATE 


User types: GOLD PAGE/COMMAND 


EDT responds: COMMAND: SET NOTRUNCATE ENTER/SUBS 


e SUBSTITUTE 


User types: GOLD PAGE/COMMAND 


EDT responds: COMMAND: S/BIGGEST/BIGGER/WH (ENTER 


This feature also extends the set of commands available to you in 
character mode to include macros that you have developed. 
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Nokeypad Character Mode 


For users whose terminals do not have a keypad, there is a 
nokeypad editor mode that can be used for character mode editing. 
Although it is somewhat less convenient to use, it does offer’ the 
functionality available in character mode. In fact, keypad 
functions in character mode are actually defined as sequences of 
one or more nokeypad commands. Table 6-7 shows examples of the 
nokeypad operations that can be performed. The user types’- the 
commands on the standard keyboard. The commands appear at the 
bottom of the screen, while the reSultS are shown at the 
appropriate place in the upper part of the screen. 


Invoking Nokeypad Mode 


To invoke nokeypad mode, the user must issue the SET NOKEYPAD 
command in line mode, and then using the CHANGE command enter 
character mode. 


Exiting Nokeypad Mode 


To exit nokeypad mode, type EXIT. The editor returns to line 


mode. Typing <CTRL/Z>, the usual method for exiting character 
mode, does not work for nokeypad mode. 


Those who may have to use a terminal without a keypad should 
now read Chapter 8, Nokeypad Editing, in the EDT Editor Manual. 


Nokeypad Character Mode Commands 


SU ae 


fe ath Rae 
ee 


oo 


ee 
ree: 


oe 
i: eae 


Se Oe es : Le ; : oe es ee 
ee 2 : 3 $ : es er ie : ee oe as 
a oe ae , . : Le 
es a oe : oe ee, ee : : : oe : 


f ee 
: ae 


oe ee 
oe 


BE Se Se 
a 


fae 


278 


USING THE EDITOR EFFECTIVELY 


LEARNING ACTIVITIES 


1. READ the following sections in Chapter 5 
of the EDT Editor Manual: 


e Locating Text 

e Movement Throughout the buffer 
e Replacing and Substituting Text 
e Using Line Editing Commands 


e Special Characters, Changing Case and 
Filling Lines 


2. DO Lab Exercises 11 through 16 for this 
module. 
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USING INDIRECT COMMAND FILES 


INTRODUCTION 


Once you become adept at uSing the system, you will notice 
many constant operations that could be automated to save 
continuous entering of commands. 


RSX-11M/M-PLUS operating systems can execute commands 
contained in a file. In addition, special commands can be added 


to control execution flow and make the command procesSS_ more 
flexible. 


The greatest benefit of this facility is being able to 


control complex processes, to eliminate typos and save the user 
from tedious errors. 


OBJECTIVES 


1. Create an indirect command file that will execute a series 
of task commands. 


2. Create a Simple indirect command file that will execute a 
series of DCL commands. 


3. Create an indirect command file that asks the user _ for 
input and controls execution flow depending on uSer input. 


4. Invoke an indirect task and CLI command file. 


RESOURCES 


1. RSX-11M/M-PLUS MCR Operations Manual 
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WHAT IS AN INDIRECT COMMAND FILE 


During the course of a terminal session, there are many 
operations performed repeatedly, for example, file maintenance and 
program development. Automating processeS can Save you a lot of 
typing and time. 


An indirect command file is a text file that contains a 
series of commands (a process) for one or more tasks. The command 


file is processed by the task(s) as though the commands’ came 
directly from the terminal. 


There are two types of indirect command files: task and CLI 
(Command Line Interpreter). 


A task indirect command file contains commands that the task 
understands. For example, the Peripheral Interchange Program 
(PIP) is the utility task DCL uses to implement file maintenance 
commands like COPY, DIR and PURGE. (To perform file maintenance 
commands when MCR is your current CLI, use PIP directly.) All _ the 
commands in the file must be commands that are understood by PIP. 


A CLI indirect command file contains commands that the CLI 
understands. For example, if we are uSing DCL, the file contains 
commands such as COPY, DIRECTORY, PURGE, FORTRAN, and _ LINK. In 
addition, a CLI command file may contain special commands that 
control the flow of execution, ask the user for input, and perform 
tests and other operations. These commands, called directives, 
require special processing before being passed on to the operating 
system. The Indirect Command Processor is the task responsible 
for processing these files. 


CREATING SIMPLE CLI COMMAND FILES 


Figure 7-1 illustrates the procedure to create an indirect 
command file. The following notes are keyed to the figure. 


@ Use an editor to create a file with a file type of .CMD. 
In the example, the file name is BUILD.CMD. The commands 
that you normally issue from the terminal are typed as 
input to the file. In the example, the DCL FORTRAN, LINK 
and PRINT commands are a typical sequence for building a 
task. You issue these commands over and over again during 
a terminal session. At the end of the editing session, 
you have a file that contains these commands. 
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@ To have the Indirect Command Processor read the file and 
execute the commands in the file, you type an @ followed 
by the file name. The default file type is .CMD. 


© The commands are read from the file and processed just as 
though they have been issued from the terminal. The 
Indirect Command Processor reads the command. If it does 
not contain directives that require interpretation by 


Indirect, the command is passed on to the CLI for 
processing. 


@ This line is the end-of-file indicator that shows’ that 
processing of the file is complete. 


> EDIT/EDT BUILD.CMD 


* | 


FORTRAN/LIST MAIN 


> @BUILD 


BUILD.CMD 


> FORTRAN/LIST MAIN 
> LINK/MAP MAIN,LB:[1,1] FOROTS/LIB 
> PRINT MAIN.LST,MAIN.MAP 


>@<EOF> 


TK-7876 


Figure 7-1 Creating and Invoking a CLI Indirect Command File 
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CREATING SIMPLE TASK INDIRECT COMMAND FILES 
Figure 7-2 shows how to create and use an indirect command 
file for a task. Typing MAC from MCR invokes the MACRO assembler. 
The format of the command line is: 
MAC taskfile,listfile=sourcefile 
Suppose you have four source files to assemble: PROG.MAC, 


RTN1.MAC, RTN2.MAC, RTN3.MAC. If you want to assemble more than 


one source file at a time, you issue the following sequence of 
commands: 


>MAC<RET> 

MAC> PROG , PROG=PROG<RET> 

MAC>RTN1,RTN1=RTN1<RET> 

MAC>RTN2,RTN2=RTN2<RET> 

MAC>RTN3, RTN3=RTN3<RETD 

MAC>“Z<RET> 

> 
This is the multiple line input format. 

Figure 7-2 shows the process to use if you want to assemble 

more than one source file by using an indirect command file. The 


first step is to create a file containing the commands for’ each 


Source file. Then the indirect command file is specified in the 
MAC command line. 
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>EDIT/EDT ASSEMBLE.CMD 


ua 


PROG, PROG = PROG 
RTN1, RTN1 = RTN1 
RTN2, RTN2 = RTN2 
RTN3, RTN3S = RTN3 


ASSEMBLE.CMD 
>MAC @ ASSEMBLE 


>MAC PROG, PROG = PROG 
>MAC RTN1, RTN1 = RTN1 
>MAC RTN2, RTN2= RTN2 
>MAC RTN3, RTN3 = RTN3 
> @<EOF> 


TK-7877 


Figure 7-2 A MCR Task Indirect Command File 


(Macro Commands are Put into a File and the File Name 
is Passed to MACRO Assembler) 
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Benefits of Using an Indirect Command File 
Makes the user's job easier by: 


e Reducing the amount of typing needed to do frequently 
performed tasks 


e Allowing the command syntax to be corrected before 
execution 


e Reducing the possibility of human error for complex, 
error-prone procedures 


e Allowing for user interaction and program flexibility 


e Automating housekeeping tasks 


LEARNING ACTIVITIES 


1. READ the following sections in Chapter 4 
of the RSX-11M/M-PLUS Operations Manual: 


e 4.1, Indirect Command Files 
e 4.2, Indirect Command Processor 


e 4.5, Switches 
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INCLUDING DIRECTIVES 
Directives 

A directive is a special command that is interpreted by the 
indirect command processor. It is distinguished by a period (.) 
as the first character in the command line, and forms a procedural 
language that allows you to: 


e Define labels 


e Define and assign values to symbols of three _ types: 
logical, numeric, and string 


e Create and access data files 

e Control the logical flow within a command file 

e Perform logical tests 

e Enable or disable any of several operating modes 

e Increment or decrement a numeric symbol 

e Control time-based and parallel task execution 

e Use special symbols for obtaining system information 
e Allow for nesting of command files 


Tables 7-1 through 7-7 list the available directives, and give 
examples of each. 
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Symbols 


A symbol is a string of ASCII characters that serve as a name 
for a memory location where a value is stored. The symbol name 


consists of a string of 1 to 6 ASCII characters. It must start 
with a letter (A-Z) or a dollar sign (S$). The remaining 
characters can be alphanumeric (A-Z,9-9) ora “S$. The following 
are legal symbol names: 

START 

SA3 

ATOZEE 


A symbol can be one of three types, which describes the kind 
of value stored in the symbol. Symbols can be 


- Logical 
- String 
- Numeric 


A logical symbol is one whose value is either true or false 
(represented by a 1 or @ respectively). A string symbol is one 
that contains ASCII characters. A numeric symbol has a = number 
stored in its memory location. The symbol type is defined when a 
value is first assigned to the symbol. 


Values Given to Symbols 


There are two sets of directives that give a value to a 
symbol, .SET and .ASK. 


~-SETS, .SETN, .SETT, .SETF and .SETL directives give a 
literal value to a symbol. For example, the values "2" and 
"PURGE" are literal values that can be assigned to a symbol; they 


do not vary. The directives .SETO and .SETD redefine the radix of 
a numeric symbol. 


-ASK, .ASKS and .ASKN directives allow for interaction with 
the user of the indirect command file. They pose a question to 
the terminal, and wait for a response to be _ typed. These 
directives allow a _ variable value to be assigned to the symbol. 
That is, each time the same .ASK directive is executed, the 
resulting value stored in the symbol varies. 
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Tables 7-1 through 7-7 list some of the available directives. 
Read through these tables to familiarize yourself with their 
Structure and contents. The sections following Table 7-7 discuss 
how to use some of the more frequently used directives. 


Table 7-1 Directives to Define Symbol Values 
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Logical Test Directives 


Table 7-2 Directives Used to Perform Tests 
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Table 7-3 Relational Operators 
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Table 7-4 Compound Logical Operators 


ea 


294 


USING INDIRECT COMMAND FILES 


Logical Control Directives 


Table 7-5 Directives Used to Control Command File Execution 
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More Useful Directives 
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Special Symbols 


Table 7-7 Special Symbols to Obtain System 
and User Information 
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LEARNING ACTIVITIES 


1. READ the following sections in Chapter 4 
of the RSX-11M/M-PLUS Operations Manual: 


e 4.4, Symbols 


e 4.6, Description of Indirect 
Directives 
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Establishing Symbols 


The following sections will discuss how to use the directives 
and symbols. The indirect command files used in the examples have 
been provided with the course materials on magnetic media. If you 


have 


trouble understanding the examples, you may want to execute 


the indirect command files at your terminal. 


Notes on Example 7-1 


The following comments are keyed to the example. 


The .SETN directive gives a_ symbol a value, and 
establishes that symbol aS a numeric symbol. The symbols 
Nl, N2 and N3 are numeric’ symbols; their contents) are 


interpreted as numbers, not ASCII characters nor Boolean 
(True, False) values. Nl contains the value 2(1@); N2 
contains the value 3(180). N3 contains the value of the 
numeric expression N1+N2*4. The expression is evaluated 
from left to right with the values of the symbols 
substituted. There is no hierarchy of numeric’ operators. 
As shown in item @, the value of N3 is 20. Different 
results will occur if the expression is written .SETN N3 
N1+(N2*4). The value of N3 under these circumstances will 
be 14. 


The .SETS directive gives a symbol a value and establishes 
that symbol as a string symbol. A string symbol is one 
whose value is a string of ASCII characters. In other 
words, the content of the symbol is interpreted as ASCII 
character(s), not a number or a true/false value. 


In item @, the expression S1+"B"+S2[1:3] has the 
following meaning: 


Take the value of Sl (which is A), concatenate (append) 
that with the ASCII character 8B, and concatenate that 
String with the first three characters contained in S2 
(CDE) to produce a value (ABCDE) and store it in symbol 
oo. 


This feature of the indirect command processor is very 
powerful for the creation of command lines, parsing of 
command lines, and general manipulation of ASCII strings. 
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The .SETT and .SETF directives set a symbol value to true 
and false respectively, and establish the symbol as a 
logical symbol. You use a logical symbol for testing a 
condition or Situation. For example, if X is set to true, 
then print the file EXAMPLE.CMD. 


These statements display the values of the symbols on the 
terminal. The .ENABLE SUBSTITUTION directive statement 
will be discussed later. 


All the commands shown thus far are in a file called 
SYMBOLS.CMD. To execute these commands, the file name 
preceded by an @ symbol is issued. There iS no _ need _ to 
supply the file type (.CMD), as the Indirect Command 
Processor uses .CMD as the default file type. 


These statements display the values of the symbols as they 
were assigned by the various .SET directives. Of 
particular interest are the values of N3 and S3, as_ they 
are a result of the evaluation of an expression. 
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e7t 
eft 
of THIS COMMAND FILE SHOWS HOW TO DECLARE A SYMBOL 
e? AND HOW TO GIVE IT A VALUE, THEREBY ESTABLISHING 
o3 THE SYMBOL TYPE 
os” 
ee” 
e? NOW TO ESTABLISH A NUMERIC SYMBOL 
er 
o? 
e? 
eSETN WN1 2, {QF THE DOT IS NOT USED TO INDICATE DECIMAL 
@ eSETN N2 3, !THE NUMBER WILL BE CONSIDERED OCTAL AND 
eSETN N3 NItN2*4, !QUTPUT WILL RE IN OCTAL 
3 
a? 
e? NOW TO ESTABLISH A STRING SYMBOL 
a? 
e? 
eSETS S1 "A" 
©@ .sets s2 "coer" 
eSETS S3 S14#"8"4+852(133)] 
er 
er 
e? NOW TO ESTABLISH A LOGICAL SYMBOL 
3 
7? 
3] eSETT X 
eSETF Y 
o? 
7 
eENABLE SUBSTITUTION 
; Ni = °N1’ 
; N2 = ‘'N2° 
3 N3 = °N3’ 
; Sis ‘si° 
; 82 = 'S2’° 
; $3 = ‘83’ 
: x = "x? 
: Y od ey? 
>@SYMBOLS 
Pat Ni = 2 
oY N2 = 3 
>3 N3 = 20 
os $1 =A 
>$ §2 = CHEF 
oF $3 = ABCDE 
3 X = T 
oF Y =F 
>@ <EOF 


Example 7-1 .SET Directive - Used to Define Symbol Value 
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Asking the User for Input 


Notes on Example 7-2 


The following comments are keyed to the example. 


A symbol may also be given a value by asking the user to 
Supply that value. The .ASKN, .ASKS and .ASK directives 
query the user for information, and wait for the user’ to 
type a response. On completion, the symbol contains the 
information the user supplies. Like the .SET directives, 
the .ASK directives also establish the symbol type as 
numeric, string or logical. In the syntax of the 
directive, the question you wish to ask immediately 
follows the symbol name. The entire command line cannot 
exceed 132(1@) characters. This directive, .ASKN, asks 
the user to supply a number. 


You may also specify a range of values that are acceptable 
for user input, and a default value if the uSer wants to 
take the default by responding with only ae carriage 
return. 


This example specifies just the default value for input, 
with no specification of a range for input. 


This example asks for a string of characters to be input. 


This example asks for a string of characters of no _ less 
than one character and no more than six characters. 


The .ASK directive asks for a true/false value. 
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3+ 

e+ 

; THIS COMMAND FILE DEMONSTRATES HOW TO ASK THE USER 

? FOR INPUT, THEREBY MAKING A COMMAND FILE “ORE FLEXIBLE 
; IN IT’S USE, 

t iad 

j* 

3 ASK THE JSER FOR A NUMERIC INPUT 

; 

, 


eASKN SYM DEFINE NUMERIC SYMBOL A 


eASKN (2235216) NUMSYM DEFINE NUMERIC SYMBOL A 
© eASKN (2:5) NUM GIVE ME A NUMBER 

3 

? 

3 ASK THE USER FOR A STRING INPUT 

? 

} 


eASKS NAME PLEASE ENTER YOUR NAME 
eASKS [136] MIDNAM PLEASE ENTER YOUR MIDDLE NAME 


; 
; 
3 
} ASK THE USER FOR A TRUE/FALSE INPUT 
} 
; 
@ eASK CONT DO YOU WANT TO CONTINUE 


eENABLE SUBSTITUTION 
SYM = °SyYM’ 

NUMSYM = °NUMSYM’ 
NUM = °NUM? 

NAME = ‘NAME’ 

MIDNAM = °MIDNAM® 
CONT = °CONT® 


we “es “9 te we we 


Example 7-2 .ASK Directive - Used to Define Symbol Value 
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Notes on Example 7-3 


The following comments are keyed to the example. 


This is the execution of command file INPUT.CMD, which 
contains the commands shown in Example 7-2. It was run on 
a hard-copy terminal to capture the actual activity 
produced by its execution. 


Comments from the command file were displayed at_ the 
user's terminal to inform the user of the purpose of the 
command file. 


This line is the result of the interpretation and 
execution of the first .ASKN directive (item @ in Example 
7-2). Indirect prompts with the question supplied in the 
-ASKN command line, and informs the user that the input 
should be an octal number ([0]). In response, the user 
types the number 8, which is not an octal number. 
Indirect performs checks on the input to see if it meets 
the specification of the .ASK directive. 


Indirect comes back and asks again for proper input. The 
user supplies the value 7 which is acceptable, and 
execution continues to the next command line in the file. 


This example shows the results of item © in Example 7-2. 
Indirect prompts the user: 


- with a question "DEFINE NUMERIC ‘SYMBOL A" 
- with the range of values for acceptable input (2 - 35) 


- with the default values (16 (8)) if the user just 
types a carriage return 


- that the number should be octal (0) 
The user types 36, which is not in range. 


Indirect comes back and asks again for the proper input. 
The user types 34, which is acceptable. 


This is the result of executing the .ASKN directive, item 


in Example 7-2. The user response was a carriage 
return, so the symbol will contain the default value of 5. 
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These two examples show the results of executing items @ 
and @ of Example 7-2. The first example asks for a 
string of characters. The second example asks for a 
String of 1 through 6 characters. Indirect will check the 
supplied string for the correct number of characters. 


This is the result of item @in Example 7-2. The user is 
to respond with either a [y] for yes or an [n] for no in 


answer to the question. The symbol, CONT, will contain a 
1 for true. 


These are the symbol names and the values they contained 
after executing this command file. If we executed the 
command file once again, supplying different answers, 
those new answers would be reflected here. 
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af we % 


@ sernrut 
>t 
Sot 
23 THIS COMMAND FILE LEMONSTRATES HOW TO ASK THE USER 
75 FOR INPUTs THEREBY MAKING A COMMAND FILE MORE FLEXIBLE 
@ >3 IN IT’S USE. 
>a 
>9- 
>s ASK THE USER FOR A NUMERIC INFUT 
29 
23 
© ok DEFINE NUMERIC SYMBOL A COI]: 8 
AT.TS6 -~- Invalid answer or terminator 
ra] > DEFINE NUMERIC SYMBOL A COIJ3 7 
>F 
ob 
6 >%* DEFINE NUMERIC SYMBOL A CO R22-35 21633 364 
AT.T56 -- Value not in range 
6 | >* DEFINE NUMERIC SYMBOL A CO Ri2-35 03163: 34 
>9 
>3 
© 2K GIVE ME A NUMBER [0 2385] 
>} 
>} 
> ASK THE USER FOR A STRING INPUT 
75 
>F 
3 | >K FLEASE ENTER YOUR NAME [CS13 ELIZABETH 
>* PLEASE ENTER YOUR MIDDLE NAME CS R21-63%3 JANNA 
>> 
3} 
>? 
>3 ASK THE USER FOR A TRUE/FALSE INFUT 
73 
>3 
9) >kK DO YOU WANT TO CONTINUE? CY/NI3 Y 
>3 
>5 
73 SYM = 7 
>3 NUMSYM = 34 
© 73 NUM = 5§ 
>3 NAME = ELIZABETH 
>3 MIDNAM = JANNA 
29 CONT = T 
>@ <EOF> 
“ye 


Example 7-3 Execution of INPUT.CMD Showing User Response 
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Making Logical Tests 


Notes on Example 7-4 


The following comments are keyed to the example. 


The .IF directive provides the feature of comparing’ two 
symbols to determine the relationship between them. For 
example, is the value of one symbol larger or smaller than 
another? Is it equal to the other? It also provides for 
taking some action depending upon that’ relationship. In 
this example, if the value of the first symbol is less 
than the second symbol, then Indirect will continue 
processing the command with the label 299. 


This is an example of a label. A label marks a place in 
the command file where control can be transferred in 
executing the file. A label begins with a period as_ the 
first character, followed by 1 to 6 characters, and 
terminates with a colon. 


The action taken as a result of comparing two symbols may 
be another directive, or an operating system command 
stated in either DCL or MCR. In this example, if Nl is 
less than or equal to ( <= ) N2, the DCL DIRECTORY command 
will be passed to the operating system for processing. 


The .IF directive in this example controls how many times 
to execute a series of commands. If the symbol N is equal 
to or greater than the number 3, processing will continue 


at the label 2@. Otherwise, processing continues at the 
label STEP2. 
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This is an example of a logical test at label "29". Three 
questions are asked where the answer to each is either yes 
or no. The next statement tests the anSwer to the first 
question. If the answer is yes, the command file 
processor continues processing at label "1@@". The next 
statement tests the answer to the second question; if it 
is false, processing continues at label "15@". If a test 
does not meet the condition specified, processing 
continues at the next statement in line. 


The next two statements are examples of compound tests. 
Using logical operators "OR" and "and", you are able to 
test for more than one simple condition. For processing 
to continue at Label "D" by executing the first statement, 
either A or B must be true, and C must be true. By using 
parentheses you can change the meaning of an expression. 
The expression contained within parentheses is evaluated 
before other operators are evaluated. The second 
Statement changes the meaning to: A must be true, or both 
B and C must be true for processing to continue at D. 
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THIS COMMAND FILE SHOWS HOW TO USE 
DIRECTIVES TO MAKE TESTS ON SYMBOLS 


se sce “e Se te 


#TESTING CHARACTERS 
eENABLE SUBSTITUTION 
eSETN WN O 
eASKS X GIVE ME A CHARACTER 
eASKS Y GIVE ME A CHARACTER 


1] .IF X LT Y .GOTO 200 
© .wext: }TESTING NUMBERS 
sASKN Ni GIVE ME A NUMBER 
,ASKN N2 GIVE ME A NUMBER 
(3 ] wIF Ni <= N2 DIR 
~SETS Si "AAD" 
wSETS S2 "AA" 
~STEP23 
«ASKS S3 GIVE ME A CHARACTER 
wIF Si >= S2+S3(1:1)] .INC N 
; N NOW EQUALS °N? 
4 ] ,IF N >= 3, .GOTO 20 
.GOTO STEP2 
7LOGICAL TESTS 
sASK A ARE YOU A PROGRAMMER 
.ASK B DO YOU WORK FOR A LIVING 
© wASK C ARE YOU RETIRED 
.IFT A .GOTO 100 
.IFF B .GOTO 150 
;COMPOUND TESTS 
6 eIFT A .OR ,IFT B .AND IFT C .GOTO D 
.IFT A .OR (.IFT 8 .AND .IFT C) .GOTO D 
.GOTO 20 
6100: 3A WAS TRUE SO B MUST BE TRUE 
sEXIT 
6150: 3768 WAS FALSE 
wEXIT 
.D3 ;THIS 1S D 


eEXIT 


22008 7X WAS LESS THAN Y 
«GOTO NEXT 


Example 7-4 Using the .IF Directive to Test Symbols 
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Notes on Example 7-5 


The following comments are keyed to the example. 


This is the result of item @ iin Example 7-4. The user 
responds to the first question by typing the letter H. 
The symbol X now contains the letter H. In the second 
question, the user responds by typing a J. The symbol Y 
now contains the letter J. The character test (X less 
than Y) is true so control passes to the label 288, which 
displays the message at the terminal. 


This is the result of item @ in Example 7-4. When the 
question prompts the user to enter an octal number, the 
user responds with 5. Symbol Nl now contains the value 5. 
In response to the second question, the symbol N2 contains 
the value 4. As a result, the DIRECTORY command does not 
execute because the test is not met. Nl is not less than 
or equal to N2. 


This is the result of item @ in Example 7-4. The value 
of the symbol N is incremented by 1 each time the value of 
Sl is greater than or equal to the evaluation of the 
expression. When N is incremented to three, processing 
continues at the label 2@. 


This is the result of item @ in Example 7-4, which 
performs a logical test. 


>@LOGICAL 
75 
F THIS COMMAND FILE SHOWS HOW TO USE 
73 DIRECTIVES TO MAKE TESTS ON SYMBOLS 
i S$TESTING CHARACTERS 
>k GIVE ME A CHARACTER CS]: H 
1) >k GIVE ME A CHARACTER CSI: J 
>3X WAS LESS THAN Y 
>sTESTING NUMBERS 
2 | >*k GIVE ME A NUMBER coi: 5 
>* GIVE ME A NUMBER [CO]: 4 
>*k GIVE ME A CHARACTER csi3 s 
>5 N NOW EQUALS 1 
3) >* GIVE ME A CHARACTER csi D 
> N NOW EQUALS 2 
>*k GIVE ME A CHARACTER csi: E 
>F N NOW EQUALS 3 
>* ARE YOU A PROGRAMMER 7 CY/NIi Y 
E DO YOU WORK FOR A LIVING? CY/NI: N 
>K ARE YOU RETIRED 7? CY/NI: Y 
>3A& WAS TRUE SO B MUST BE TRUE 


2?@ <EOF> 
? 


Example 7-5 Execution of LOGICAL.CMD and the Results 


of User Input 
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Controlling Execution Flow 


o3 
o? 
eo? THIS COMMAND FILE SHOW HOW TO USE CONTROL 
eo} DIRECTIVES TO CONTROL THE EXECUTION OF A 
e? ' COMMAND FILE 
of 
o? 
oASKN SYM #14: DEFINE NUMERIC SYMBOL A 
eASKN(2.2335,.816.)] NUMSYM #2: DEFINE NUMERIC SYMBOL A 
eASKN(E 825.) NUM #38 GIVE ME A NUMBER 
eASKS NAME #48 PLEASE ENTER YOUR NAME 
eASKS(136)] MIDNAM #5: PLEASE ENTER YOUR MIDDLE NAME 
eASKS(1230) LASTNM #62 PLEASE ENTER YOUR LAST NAME 
eASK CONT #78 DO YOU WANT TO CONTINUE 
elFF CONT EXIT 
eENABLE SUBSTITUTION 
«IF NUMSYM LT 17, eGOSUB STEP2 
eoIF NUM EO 5S, .GOTO STEP3 
eSTEPLS 
ySYM = °SYM’ 
sNUMSYM = “NUMSYN’ 
NUM = “NUM? 
eSTOP 
eSTEP23 
3 
3 
3 
SHELLO °NAME’ °MIDNAM’ °LASTNM’ 
7 
e 
FHERE IS HOW YOU RESPONDED TO THE QUESTIONS: 
v 
eRETURN 
eSTEP33 


?YOU TOOK THE DEFAULT ON QUESTION #3 SO I WON’T 
7SHOW YOU HOw YOU RESPONDED TO THE OTHER QUESTIONS. 
eSTOP 


Example 7-6 Command File Showing How to Control Execution Flow 
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>@CONTROL 
>k #13 DEFINE NUMERIC SYMBOL A [013 3 


>% $23 DEFINE NUMERIC SYMBOL A CD K22.-35. 0216.12 


>k #33 GIVE ME A NUMBER CD Dt5.]3 
>* #43 PLEASE ENTER YOUR NAME CSI]: ELIZABETH 
>*% #5: PLEASE ENTER YOUR MIDDLE NAME CS R21-633 


>k #73; DO YOU WANT TO CONTINUE? CY/NI3 Y 


ae 
> we S62 ~«e 


JANNA 
2k #63 PLEASE ENTER YOUR LAST NAME CS R21-3033 VAN 


12, 


>$HELLO ELIZABETH JANNA VAN 

>} 

>} 

>$HERE IS HOW YOU RESPONDED TO THE QUESTIONS? 

>} 

>$YOU TOOK THE DEFAULT ON QUESTION #3 SO I WON’T 
>3SHOW YOU HOW YOU RESPONDED TO THE OTHER QUESTIONS. 
>@ <EOF> 

> 

> 

>@CONTROL 


>k $13 DEFINE NUMERIC SYMBOL A [CO]? 55 


2 #23 DEFINE NUMERIC SYMBOL A CD R82--35- 0316.33 2 


>k #3: GIVE ME A NUMBER CD 035.1: 32 
>* #43 PLEASE ENTER YOUR NAME CS1$ JOHN 
>k #53 PLEASE ENTER YOUR MIDDLE NAME CS R31-63; 


>k #73 DO YOU WANT TO CONTINUE? CY/NI3 Y 


sew 
| @> Sr we 


*#HELLO JOHN JACOB JINGLEHEIMER 


MoS 


*, 


HERE IS HOW YOU RESPONDED TO THE QUESTIONS: 


“=> “SP we 


WN 


>SSYM = 55 

>eNUMSYM = 2 

>sNUM = 32 

>@ <EOQF> 

>@CONTROL 

7k #13 DEFINE NUMERIC SYMBOL A COJ? 72 


>k& #23 DEFINE NUMERIC SYMBOL A CB Ri2--35. BI1ié6.]3 


2k #33 GIVE ME A NUMBER CD D35.33 62 
2% #43 PLEASE ENTER YOUR NAME CS]; PAUL 
>k #5: PLEASE ENTER YOUR MIDDLE NAME CS R21i-623 


JACOB 
>* #63 PLEASE ENTER YOUR LAST NAME CS Kii1-30]% JINGLEHEIMER 


H. 


26 


>* #63 PLEASE ENTER YOUR LAST NAME CS Ri1-30]7% HARVEY 


>% #73 DO YOU WANT TO CONTINUE? CY/NI: N 
>@ <EOF> 


Example 7-7 Execution of CONTROL.CMD and User 
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Setting Operating Modes 
Notes on Example 7-8 
The following comments are keyed to the example. 


@ Quiet mode suppresses the echoing of operating system 
command lines at the terminal. In this example, if the 
user answers yesS to the question, the .ENABLE QUIET 
statement turnS quiet mode on. In this case, the SHOW 
TASKS ACTIVE command would not echo at the terminal. 
However, the results of issuing the command would be 
displayed. If the uSer anSwers no to the question, the 
SHOW TASKS ACTIVE command would be echoed, and the results 


of issuing the command would be displayed. You use 
e-ENABLE and .DISABLE to turn the operating modes on and 
off. 


@ Substitution mode allows for the substitution of a 
symbol's value for the symbol in the command line. For 
example, if the user answers the question, SPECIFY SOURCE 
FILE, with NOTES.TXT, the statement TYPE 'FILE' would 
become TYPE NOTES.TXT. Two steps must be accomplished for 
this mode to work correctly. Substitution mode must be 
enabled, and the symbol must be enclosed in single quotes 
where the substitution is desired. 


@ lowercase mode allows characters read from the terminal in 
response to .ASKS directives to be stored in the string 
Symbol without lower- to uppercase conversion. 


4 | This mode allows an escape character to be an acceptable 
response to a .ASK directive. 


@ This mode allows the user to output lines to a _ secondary 
file. Enabling this mode directs Indirect to output the 
lines between the .ENABLE DATA and - DISABLE DATA 
statements to a secondary file. This is most useful for 
dynamically creating another indirect command file, or a 
data file for another task. 


6 Global symbol mode provides for symbols whose names’ begin 
with a $ to be recognized in all levels of command files. 
Those symbols whose name do not begin with a $ are only 


recognized in the level of the command file in which they 
are defined. 


For more information on the various operating modes, refer to 
Chapter 4 of the MCR Operations Manual. 
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t+ 
3+ 
; THIS COMMAND FILE SHOWS HOW THE OPERATING MODES 
: WORK, 
; 
; 
; LOWER CASE 
; DATA 
; GLOBAL 
; SUBSTITUTION 
’ ESCAPE 
; QUIET 
t ad 
3° 
’ 
@ ;: quiet Move 
; 


eASK QUIET 90 YOU WANT COMMAND LINES SUPPRESSED 
eIFT QUIET ,HNABLE QUIET 

oIFF QUIET DISABLE QUIET 

SHOW TASKS ACTIVE 


; 
©@ ; —s supsrirurion move 
; 
sENABLE SUBSTITUTION 
eASKS FILE SPECIFY SOURCE FILE 
TYPE °FILE’ 


LOWER@CASE MUDE 


we te te 


.DISABLE QUIET 
.ASK CASE DO YOU WANT LOWER*CASE ENABLED 
LIFT CASE .ENABLE LOWERCASE 
VIFF CASE ,DISABLE LOWERCASE 
,ASKS A DEFINE STRING SYMBOL A 
rR? 
} 
@ +  ESCAPF RECOGNITION Mone 


; 
sIF YOU WANT A LIST OF OPTIONS, TYPE <ESC> 
eENABLE ESCAPE 
eASKS A ENTER OPTION 
eIFT <ESCAPED> GOTO LIST 
eSTFPIs 


; 
©@ ; bara Move 


eOPEN ASSEMBLE.CMD 

eENABLE DATA 

eENABLE SUBSTITUTION 

MACRO/LIST °’SX°’ 
eDISABLE DATA 

eCLOSE FILE, TXT 


3 
3 GLOBAL MODE 


eENABLE GLOBAL 
eSETS SX "TEST" 
@ASSEMBLE 
«STOP 
eLIST: ;OPTIONS ARF: ACADD), SCSUBTRACT),M (MULTIPLY) 
GOTO STEP! 


Example 7-8 Command File Showing Operating Mode Usage 
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Notes on Example 7-9 


The following comments are keyed to the example. 


In this example, the use of quiet mode is’ shown. In 
response to the question, the uSer answers yes. The DCL 
command, SHOW TASKS ACTIVE, which executes, does not’ echo 
at the terminal. However, the results of the command do. 


In this example, quiet mode is still active. The TYPE 
TEST.MAC command does not echo on the terminal. However, 
the string "TEST.MAC" replaces 'FILE' in the TYPE command 
in item 2 of Example 7-8. This feature allows your 
indirect command file to work for variable file names 
rather than just one file. 


In this example, lowercase characters entered in response 
to a question remain in lowercase. If this mode was not 
enabled, lowercase letters would be converted to uppercase 
on input. This could be a problem later when comparing 
characters in symbols if the case did not match (i.e., 
uppercase to lowercase). 


Escape recognition mode permits the response to an_ .ASK, 
-ASKN, or .ASKS directive to be an escape character. A 
question answered this way sets the special logical symobl 
<ESCAPE> to true. You can then test this symbol for true 
or false. 


This example creates an indirect command file that will be 
used in the following example. The .OPEN directive opens 
a file with the name supplied with the directive. In this 
case, the file name is ASSEMBLE.CMD. The lines following 
the -ENABLE DATA statement up to the .DISABLE DATA 
statement are output to the file ASSEMBLE.CMD. The .CLOSE 
statement closes the file. A DIR command issued after 
this operation would show a file called ASSEMBLE.CMD in 
the user's UFD. 
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@ In this example, ASSEMBLE.CMD is invoked from the indirect 
command file. This is a second level of indirection. The 
-ENABLE GLOBAL statement allows for the recognition of the 
symbol S$X from another indirect command file. The second 
Statement gives a value of the string TEST to the symbol 
SX. The next statement invokes the indirect command file 
that was created in the previous example. Processing now 
continues from the indirect command file ASSEMBLE.CMD. 
The symbol $X is recognized in this file, and substitution 
takes place. This creates the command line of MACRO/LIST 
TEST, which is sent to_ the operating system for 
processing. Quiet mode was disabled in example 3 above, 
so the command line is echoed at the terminal. The 
results of the assemble are also shown. 


>@OPERATING 
>t 
>ot 
25 THIS COMMAND FILE SHOWS HOW THE OPERATING MOLES 
>o WORK. 
>3 
>§ THERE ARE SIX OPERATING MODES: 
25 LOWER CASE 
>§ DATA 
2 GLOBAL 
9 SUBSTITUTION 
> ESCAPE 
3 QUIET 
; 
5 
3 
3 
5 


way vo 


QUIET MODE 
1] >* DO YOU WANT COMMAND LINES SUPPRESSED? CY/NI: Y 
MCRese 
SHOTSS 
AT.T56 


@ >* SPECIFY SOURCE FILE CS1: TEST.MAC 
+MACRO EXIT$S ERR 
»MCALL DIRS 


MOV (PC +9-( SPF) 
+BYTE Siserl 
DIRS 


+ITIF NE <ERR>,» CALL ERR 
»ENDM EXIT$S 
© >*k TQ YOU WANT LOWER-CASE ENABLED? CY/NI?3 Y 
>k DEFINE STRING SYMBOL A CSI: This is Lower Case 
*e This is Lower Case 


oF 
>} ESCAPE RECOGNITION MODE 
oF 
© >s1F You WANT A LIST OF OPTIONS, TYPE <ESC> 
>* ENTER OPTION [CS]? 
>$OPTIONS ARE? ACADD), S(SURTRACT) sm (MULTIPLY) 
>F 
@ >i vata mone 
>} 
4 
>} GLOBAL MODE 


>} 

© >Macko/List TEST 
ERRORS DETECTED: 1 
TEST» TEST/SP=TEST 
>@ <EOF> 


Example 7-9 Execution of OPERATING.CMD and User Response 
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Using Special Symbols 


Table 7-7 lists some of the special symbols available for 
your use. These symbols provide system information and replies to 
queries presented during command file execution. The symbol names 
are enclosed in brackets and are used in the same manner as 
user-defined symbols. 


Notes on Example 7-10 


The following comments are keyed to the example. 


Nine different special symbols are used in this example. 
When the file is executed, these comment lines will be 
displayed at the terminal with the values of the _ special 
symbols substituted. 


In this example, the user is asked to input a string of 
characters. The special symbols are tested and, if found 
true, the command following the statement is executed. 


If the user types an <ESC> (eScape character), the 
indirect command file will exit. If all alphanumeric 
characters are typed, Indirect will display the message at 
the terminal that all characters typed were alphanumeric. 
If all characters were Radix-58, another message is 
displayed. In the .SETN statement, the number of 
characters in the input string is saved in the _ symbol 
<STRLEN> and then output with a message. 
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THIS COMMAND FILE SHOWS HOW TO USE THE SPECIAL 
SYMBOLS THAT ARE AVAILABLE TO THE USER 


eENABLE SUBSTITUTION 


we te Ye “8 te Te Ge Te YO NO 


THE USER OF THIS COMMAND FILE IS ’<UIC>*’ AND HE 

ITS RUNNING ON AN RSX SYSTEM WITH °<MEMSIZ>*’ K OF CORE, 
HIS DEVICE IS °<SYDISK>*’<SYUNIT>*’, HE IS PRESENTLY 
USING °<CLI>’ AS HIS CURRENT COMMAND LANGUAGE 
INTERPRETER, THE DATE IS ‘°<DATE>’ AND THE TIME THIS 
COMMAND FILE IS RUNNING JIS ‘<TIME>’, THE LIBRARY 

FOR THIS SYSTEM IS IN °<LIBUIC>’ AND THE SYSTEM UIC IS 
*<SYSUIC>’, 


eASKS USER GIVE ME A STRING 
oIFT <ESCAPE> EXIT , 

2 | eIFT <ALPHAN> 7YOU TYPED ALL ALPHA/NUMERIC CHARACTERS 
eIFT <RADSO> ;YOQU TYPED ALL RAD50O CHARACTERS 


eSETN STRLEN <STRLEN> 
eSETD STRLEN 


sYOU JUST TYPED “STRLEN’ CHARACTERS 


; 


Example 7-19 


Command File Showing Special Symbol Usage 
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Notes on Example 7-11 


The indirect command file, SPECIAL.CMD, is executed three 
times in this example. Each time, Indirect substitutes 
the system information for the special symbols. For 
example, the special symbol <UIC> represents the UIC in 
which the indirect command file is processing. The value 
of this symbol in this example contains the character 
string [385,303]. Indirect substitutes this value in’ the 
comment line before displaying the line at the terminal. 
You may want to try running this example on your system to 
see how it works and how the information changes. 
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@SFECTAL 


THIS COMMAND FILE SHOWS HOW TO USE THE SPECIAL 
SYMBOLS THAT ARE AVAILABLE TO THE USER 


THE USER OF THIS COMMAND FILE IS £3057303] AND HE 

IS RUNNING ON AN RSX SYSTEM WITH S12 K OF CORE. 

HIS DEVICE IS DBO. HE IS FRESENTLY 

USING DCL AS HIS CURRENT COMMAND LANGUAGE 
INTERPRETER. THE DATE IS 22-SEP-81 AND THE TIME THIS 
COMMAND FILE IS RUNNING IS 14309307. THE LIBRARY 

FOR THIS SYSTEM IS IN C1254] AND THE SYSTEM UIC IS 
C4754]. 


mS AE NEN SE MO NE OO OO Oe 


a> <a> Qe ~er ~e> or “ar erp SP “OP “ah “a> EP wee aP “OP ~ee 


GIVE ME A STRING CS1%$ THISISASTRING 
YOU TYPED ALL ALPHA/NUMERIC CHARACTERS 
sYOU TYPED ALL RADSO CHARACTERS 


*, 
e 


ra 


ue 


7s YOU JUST TYPED 13 CHARACTERS 


< 


<EOF> 
SPECIAL 


wo AS 


THIS COMMAND FILE SHOWS HOW TO USE THE SPECIAL 
SYMBOLS THAT ARE AVAILABLE TO THE USER 


THE USER OF THIS COMMAND FILE IS €3052303] AND HE 

IS RUNNING ON AN RSX SYSTEM WITH S12 K OF CORE. 

HIS DEVICE IS DRO. HE IS PRESENTLY 

USING DCL AS HIS CURRENT COMMAND LANGUAGE 
INTERPRETER. THE DATE IS 22-SEP-81 AND THE TIME THIS 
COMMAND FILE IS RUNNING IS 14309339. THE LIBRARY 

FOR THIS SYSTEM IS IN £12543 AND THE SYSTEM UIC IS 
C4/54). 


‘af ME ME ONE NE OS 


eww yw yo 


GIVE ME A STRING CSI]! THIS IS A STRING 


ne 


“e 


YOU JUST TYPED 16 CHARACTERS 


<EOF> 
>@SPECIAL 


THIS COMMAND FILE SHOWS HOW TO USE THE SPECIAL 
SYMBOLS THAT ARE AVAILABLE TO THE USER 


sf ge ™, 


24S 
e 


“e 


- 2 7 
Se oa 


THE USER OF THIS COMMAND FILE IS (£305»303]3 ANDI HE 
IS RUNNING ON AN RSX SYSTEM WITH S12 K OF CORE. 
HIS DEVICE IS DBO. HE IS FRESENTLY 
USING DCL AS HIS CURRENT COMMAND LANGUAGE 
INTERPRETER. THE DATE IS 22-SEP-81 AND THE TIME THIS 
COMMAND FILE IS RUNNING IS 14209254. THE LIBRARY 
tae Vane SYSTEM IS IN (£1°54] AND THE SYSTEM UIC IS 
ee) + 


w oN 
<e> “ap wad “GD <a> “er sed “er sam <am sen <em <an er fe) FE) <a> “E> ae QE ee eo ~en ~we “en “Om <n <r an “a> wan em sem “er fG) fay “er eo wer 


Sowa ww wow Aw 


& GIVE ME A STRING CSI! THESIS32ASSTRING 
>$YOU TYPED ALL ALFHA/NUMERIC CHARACTERS 
>$YOU TYPED ALL RADSO CHARACTERS 


“ey 
>$YOU JUST TYPED 16 CHARACTERS 


a 


> 
“9 


7@ <EOF> 


uf 


Example 7-11 Execution of SPECIAL.CMD 
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Examples 7-12 and 7-13 show how to use the commands you have 
learned to automate processes that you perform every day. In 
Example 7-12, the first command file will change your current CLI 
to either MCR or DCL, depending on which CLI is presently active 
at your own terminal. The second example will print the time of 
day, and the third will send a message file to a terminal. 


Example 7-13 is a file maintenance task that you perform 
every day. It will edit a file, print a copy of the edited files, 
and then clean up your work area by puring unnecessary copies of 
the file when you are finished. You may want to try these at your 
terminal to see the results. 


of THIS COMMAND FILE WILL CHANGE THE CURRENT 
of CLI TO EITHER DCL OR MCR DEPENDING UPON WHICH IS 
oF CURRENT, 


eENABLE QUIET 
oIF <CLI> EQ "DCL" ,GOTO 10 
SET /DCLSII: 
eEXIT 
0108 SET TERMINAL MCR 


eGNABLE SUBSTITUTION 
eSETS t <time> 
:THIS IS THE CORRECT TIME: ‘T* 


THIS FILE WILL SEND A MESSAGE FILE 
; TO A SPECIFIED TERMINAL 
; 


~e 


eENABLE SUBSTITUTION 
eASKS FI TERMINAL NUMBER 
eENABLE QUIET 
PIP TT°FI°SsTEXT, TXT 

3 


Example 7-12 An Indirect Command File to Send Message to Terminal, 
and Change Current CLI 
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USING INDIRECT COMMAND FILES 


eo? This command file supports file editing and 
e? management, allowing user to edit, purge, 
ee print, and run files, 
eENABLE LOWERCASE {We want lowercase 
eENABLE SUBSTITUTION fand symbol substitution 
a? 
] Some definitions: 


eSETF IND 


e? Get file type 
21083 eASKS TYPE FILE TYPE EXTENSION (E.,G., "CMD") 
TEST TYPE {Null type? 


elF <STRLEND EQ 0 «GOTO ERR1 !Then error 

o? Get file name 

21583 eASKS NAME NAME FILE YOU WISH TO EDIT ( NO TYPE) 

eo? Make complete filespec by concatenating name and type 
eSETS FILE NAME+" ."+TYPE 

ee Valid name? 
eTEST NAME 
eIF <STRLEN> EQ 0 eGOTO ERR2 !lf no, report error 

Pat Edit file 

22088 EDT "FILE? 

e? After EDT exit, ask {if another edit is desired 
eASK REPEAT DO YOU WANT TO EDIT THE SAME FILE AGAIN 
elFT REPEAT .GOTO 206 

o} If filetyoe was .CMD (indirect command file) 

3 see if user wants to execute file 
elF TYPE EQ "emda" ASK IND DO YOU WANT TO RUN “FILE® 
eIF TYPE EQ "CMD" .ASK IND DO yOU WANT TO RUN ‘FILE’ 
elFT IND Q@°FILE’ !If yes, run it 

e? to RUNOFF and print .MEM file on LPs: 

3 See if user wants to print file 


ASK PRINT DO YOU WANT TO PRINT THE FILE 
eIFT PRINT PRINT ‘FILE’ %tIf yes, orint it 


eo? See if user wants to purge previous versions of file 
23088 e ASK PURGE DO YOU WANT TO PURGE ’FILE’ 
oF If yes, send to PIP 
eIFT PURGE PIP °FILE’/PU/LD 
e} See if user wants to edit another file 
«ASK OTHER 00 YOU WANT TO EDIT ANOTHER FILE 
eI FT OTHER «GOTO 19S !Tf so, loop 
»GOTO 100 


ERROR PROCESSING 


FILE TYPE ERROR = PLEASE ENTER THE FILE TYPE (EXTENSION 
OF THE FILE YOU WISH TO EDIT) 


«GOTO 108 
eERR23 
; ; 
3 FILE NAME ERROR = PLEASE ENTER THE FILE YOU WISH TO EDIT 
; 
«GOTO 15s 
21003 


Example 7-13 An Indirect Command File to Edit, Print 
and Purge Files 


321 


CONTROLLING 
TASK EXECUTION 


CONTROLLING TASK EXECUTION 


INTRODUCTION 


You have seen how the operating system manages resources’ and 
controls memory sharing and CPU time. [In this module you will 
learn how to set up and/or change various task parameters’ that 
affect how the task competes for memory and CPU time. 


OBJECTIVES 


1. Know when and how to change task parameters, such as 
priority, that affect task execution. 


2. Use the RUN command for immediate and time-based 
scheduling of a task. 


3. Install a task as an MCR spawnable task, and how to invoke 
such a task using an MCR command. 


RESOURCES 


1. Introduction to RSX-11M/M-PLUS Systems 
2- RSX-11M/M-PLUS Command Language Manual 
3. RSX-11M/M-PLUS MCR Operations Manual 


4. RSX-11M/M-PLUS Task Builder Manual 
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HOW RSX MANAGES TASKS 
Priority and Scheduling 


In module 1, Overview, a discussion on how RSX-11M/M-PLUS 
manages tasks indicates that a task's' priority and its state 
govern when it will get CPU control. The highest-priority, 
ready-to-run task is given control of the CPU. Once a task 
controls the CPU, it continues to execute until it completes, 
becomes blocked, or a_ task of higher priority is ready-to-run. 
The current task is the task that holds CPU control. The 
scheduler changes the current task to the higher priority task 
through the occurrence of a significant event. When a significant 
event occurs, the scheduler looks at the Active Task List (ATL) to 
select the current’ task. Only those tasks in the ATL are 
considered for CPU scheduling. 


In Figure 8-l, the arrows weaving through the System _ Task 
Directory point to the tasks that are active and competing for 
resources. TASKB, TASKD, TASKE, TASKG, TASKI, and TASKJ are the 
active tasks. The scheduler, in searching this list, will select 
TASKE as the current’ task. It is the highest-priority, 
ready-to-run task. If TASKE completes and no other task state 
changes occur in the list, TASKJ will then be the next task 
selected as the current task. Resource scheduling only occurs at 
the time of a Significant event. If you need to, refer to Table 


1-3 to refresh your memory on what events constitute significant 
events. 


Figure 8-2 illustrates the various task states. 
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SYSTEM TASK DIRECTORY (ALL INSTALLED TASKS) 


TASK A 
PRI = 248, 


ACTIVE TASK LIST TASK B 


PRI = 240, BLOCKED 


TASK C 
PRI = 232. 


TASK D 
PRI = 182, ce 
* TASK E 


NBLOCKED 
PRI = 150, i 


TASK F 

PRI = 120. 

* CURRENT TASK 
BLOCKED (NOW EXECUTING IN 
THE CPU). 


TASK G 
PRI = 75. 


TASK H 
PRI = 50. 


TASK | 
a PRI = 50. 
TASK J 


PRI = 50. 


BLOCKED 


UNBLOCKED 


TK-7504 


Figure 8-1 Highest Priority Ready-To-Run Task Gains 
CPU Control 


328 


CONTROLLING TASK EXECUTION 


Task States 


The following is a review of task states and their meaning: 


1 


2 


UNKNOWN 


KNOWN 


DORMANT 


ACTIVE 


READY — 
TO-RUN 
BLOCKED 


CURRENT 


A task for which there is no STD entry 


A task for which there is a STD 


A task for which there is a STD 
but no ATL entry (no request to 


A task for which there is a STD 
ATL entry (a request to run has 


entry 


entry 
run) 


and an 
been made) 


An active task not waiting for any 


event 


An active task waiting for an event 


An active task with current CPU control 
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OEE 


UNKNOWN KNOWN 


DORMANT ACTIVE 


EXECUTIVE 


RUN GRANTS CPU 


EXECUTIVE 
GRANTS CPU 
TO OTHER TASK 


TASK WAITS 
FOR EXTERNAL 


EVENT 
REQUIRED 


EXTERNAL 
EVENT OCCURS 


BLOCKED 


TK-7496 
Figure 8-2 Task States 


(Every Task is Allocated CPU, and Memory-Dependent Upon its State) 
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Memory Allocation 


Before an active task can gain control of the CPU, it must be 
memory-resident. Memory allocation occurs on a 
partition-by-partition basis. A task's state, priority, and _ the 
partition in which the task was built to run are all considered 
when a task memory allocation request iS made. The task loads 
into the partition if there is room for it, and no higher-priority 
task is competing for the same spot. If there is no room in the 
partition, the task must wait until the operating system can 
provide memory space. The task cannot be loaded into another 
partition. 


The operating system checks to see if it can provide memory 
space for the task by searching the partition for a memory- 
resident task of lower-priority that is checkpointable. If found, 
that task will be checkpointed to allow loading of the higher- 
priority task. The memory allocator checkpoints as many tasks as 
necessary to load the higher-priority task. However, all 
checkpointed tasks will be of lower-priority, and have the 
checkpoint characteristic built into the task. 


LEARNING ACTIVITY 


1. DO Written Exercises 1 through 3 for this 
module. 
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USING TASK BUILDER FACILITIES 


The Task Builder defaults assume typical usage and_ storage 
requirements. You can override these defaults by using switches 


and options, thus tailoring a task for itS own input/output and 
storage requirements. 


Some attributes that can be altered: 
e Task Name 
e Priority 
e Partition 
e Logical Units 
e Checkpointability 


Others can be found in the RSX-11M/M-PLUS Task Builder Manual. 


Assigning a Task Name 


Task names by default are the first six characters of the 
task image file name. Sometimes, this naming convention is not 
Suitable. If so, the name can be specified at task-build time by 
using the /OPTIONS qualifier on the LINK command, as shown in the 
example below. The Task Builder will prompt with Option?. The 
user then supplies the TASK option with a 1 to 6 character name. 
The Task Builder will than prompt again with Options?. More 
options can be entered if needed. Complete the process by typing 
a carriage return in response to the prompt. The Task Builder 
will then process the command data to create a task image file. 


>LINK/OPTIONS PROG 


Option? TASK=QRST 
Option?<CR> 
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Setting Task Priority 


The priority of a task is also established at task-build 
time. If not overridden at install time, the task-build priority 
becomes the default priority at which the task will run. If a 
task is run on a multiuser protection system, it will not run at a 
priority greater than the system default priority (58), unless it 
is installed or run from a privileged terminal. 


The priority is a decimal integer in the range of 1-258. The 
default priority is 5@. If a real-time task is being created, its 
priority should be in the range of 15@-258@. To specify the 
priority when building your task, use the following commands: 


>LINK/OPTIONS PROG 
Option?PRI=159 
Option?<CR> 


Indicating a Partition 


A third consideration when building your task is the 
Partition in which the task is to run. Partition selection is 
dependent upon the task's function. If it is a real-time task, 
you will probably build the task to run in its own special 
Partition so that it does not compete with general tasks for a 
position in memory. If the task is for general use, you will 
probably build it to run in the general partition called GEN. GEN 
is the default partition used if you do not specify a partition. 
The partition in which a task runs can be overridden when the task 
is installed, without having to rebuild the task. The following 


example shows how to specify a different partition when building 
your task. 


LINK/OPTIONS TEST 


Option? PAR=DRVPAR 
Option?<CR> 


333 


CONTROLLING TASK EXECUTION 


Making a Task Checkpointable 


Generally, tasks are built checkpointable. This means’ the 
task can be swapped out of memory and stored on disk to make room 
for a higher-priority task. When the system checkpoints a _ task, 
it places the task's memory image out on disk. There is a file on 
each disk volume called CORIMG.SYS. The system uses this file to 
temporarily store checkpointed task images. When space becomes 
available again, the system reads the task image from the 
checkpoint file and writes it back into memory. The task is again 
competing for CPU time. 


In addition, space can be allocated within the task image 
file to store the memory image of a checkpointed task. This 
guarantees available checkpoint space even when the system 
checkpoint file is full. The following command examples show how 
to build a task to be checkpointable. The default is not 
checkpointable. 


LINK/CHECKPOINT: SYSTEM VIPPROG 
LINK/CHECKPOINT: TASK VIPPROG 


In the first example, the task is built to be checkpointed to 
the system checkpoint file. 


In the second example, the task is built with space reserved 
within the task image file for checkpointing space. The size of 
the task image file created with this qualifier will be 
approximately twice the size of the task image created with the 
/CHECKPOINT: SYSTEM qualifier. 


In both cases, the tasks, if checkpointed, will first be 
written to the System Checkpoint File. 
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Assigning Logical Units 


Example 8-1 shows the process of associating logical units 
with the actual physical device that is to be used _ for 
input/output. A source program uses logical units for reading and 
writing to devices (I/0). They are called logical units because 
at this point in the program development process, the physical 
device to which the input/output will be done is not known. It 
may be known that a certain type of disk drive is to be used, but 
the specific unit probably is not. Furthermore, you would not 
want to “hardwire" the real device name into the program. It is 
advantageous to delay association with the real physical device as 
long as possible. 


In item @in Example 8-1, in the statement WRITE (1,19) 
VARI], "“1" ais the logical unit number. There are three logical 
units shown in this short program fragment. Two of them are 
output devices (WRITE statements) and one iS an input device (READ 
statement). This program will read from one file and write to two 
devices. At this point, you do not know what devices will be used 
for the files. 


When the task is linked using the /OPTIONS qualifier, you 
must further inform the Task Builder about the devices. First, 
you must tell how many I/O units the program has (item @ in the 
example). The Task Builder will assign six units by default if 
you do not specify a number. In the case of FORTRAN programs, the 
Task Builder allocates seven units. 


Next, you must give the Task Builder the physical, logical or 
pseudo device assignments for the logical units. This is shown in 
items @, @. and @of the example. The ASG keyword accepts 
assignments with the following syntax: Physical device:Logical 
unit. In this example, the logical unit number 1 is’ associated 
with the pseudo device SY: (the user's default device). Every 
time this program writes to logical unit 1, output will appear on 
the user's default device (item@). The program will read from 
logical device LZ:, which correlates to logical unit 2. As this 
is a logical device, the connection to a physical device has not 
been completed. After task-building, another step is’ required 
before this program can be successfully run. The logical device 


LZ: must be assigned to a physical device using the ASSIGN 
command. 


Logical unit 3 has been associated with the physical device 
MM@:, the first magnetic tape unit on the system. Every time the 
Program does a write to logical unit 3, output goes to MM@:. 
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After the task has been built, and before it can be run 
properly, the association between logical device LZ: and some 
physical device must be accomplished. This is done with the DCL 


ASSIGN command, as shown in item @of the example. Only then can 
the program be run. 


By delaying logical unit assignments until just before 
running the program, you provide the program with device 
independence. This is especially useful when a device is not 
working, or is busy. For example, suppose the magnetic tape unit 
is being used by Someone else, and you wish to run this_ program, 
which was built to use the magnetic tape unit. You might either 
wait until the tape unit becomes free (which could be a long 
time), or rewrite and rebuild your program to write to another 
magnetic tape unit. These two solutions are time-consuming and 


tedious. By using the procedure in Example 8-1, you save time and 
frustration. 


When you build your task you may specify up to 25@ units. 
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PROG.SRC 


WRITE (1,198) VARI 
READ (2,15) VAR2 


WRITE (3,25) VAR3 


>LINK/OPTIONS PROG 


OPTIONS? UNITS=3@ 
OPTIONS? ASG=SY:1,LZ:2,MMO: 3 
OPTIONS? <RED@ @ C5 ] 


>ASSIGN DK: LZ: © 
>RUN PROG 


Example 8-1 Associating Logical Units with Physical Devices 


Notes on Example 8-1 


The following comments are keyed to the example. 


Logical unit numbers represent a device for I/O 
Telling the Task Builder there are 3 input/output units 


Assigning logical unit 1 to user's default disk (pseudo 
device) 


Assigning logical unit 2 to the logical device LZ: 


Assigning logical unit 3 to a physical device (the first 
magnetic tape unit) 


Before running the task, the association between’ the 
logical device LZ: and some physical device must be made 
for the program to execute correctly. 


The association between SY: and the user's’ default 


physical device was made when the user logged on, or 
through the DCL ASSIGN command. 
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task 


to override some of these 
it is not necessary to rebuild a task 
is it necessary to 


how 
Nor 


Table 8-1 shows 
attributes. For instance, 
to run it at a different priority. 
reinstall a task to have it run at a different priority. 
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Characteristics of a task can be changed 


task. 
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Table 8-2 shows the MCR commands that are the equivalent of 
the DCL commands used earlier. By typing TKB<RET>, you are 
invoking the multiple input line format of the Task Builder. You 
must use this form to enter options. (Input files can also be 
typed on multiple lines.) When you type (/), TKB prompts’ with 
ENTER OPTIONS. Typing (//) terminates option mode and the Task 
Builder creates the task image file. 


Table 8-2 MCR Commands to Invoke the Task Builder to 
Override Task Builder Defaults 


at ‘task-build time =e reP, PROGREROGCRET> 


There are many more task characteristics that can be 
specified at task-build time. The few mentioned here are the most 
frequently used. For further information regarding the use of the 
Task Builder and the options and switches available, refer to the 
RSX-11M/M-PLUS Task Builder Manual. 
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LEARNING ACTIVITIES 


READ the following in the RSX-11M/M~-PLUS 
Task Builder Manual: 


e Chapter 1, Introduction and Command 
Specification 


e Chapter 18, Switches 
-~ Section 198.1, Switches 


- Section 19.1.6, 
/CP--Checkpointable 


e Chapter 11, Options 


- Section Ll Lek, ASG--Device 
Assignment 


- Section 11.1.9, PAR--Partition 
- Section 11.1.2@, PRI--Priority 
- Section 11.1.27, TASK--Task Name 


- Section 11.1.38, UNITS--Logical 
Unit Usage 


READ the following sections in the 
RSX-11M/M-PLUS Command Language Manual: 


@e Chapter 6, Linking the Task 


DO Written Exercises 4 through 13 for 
this module. 
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INSTALLING A TASK 


Installing a task in the System Task Directory (STD) is done 
by issuing the INSTALL command. It makes the task known to the 
System and records the task name, priority, partition and disk 
address of the task image file in the STD. Before any task can be 
run, it must be installed. Installing a task does not cause it to 
execute, but does cause the task's state to be KNOWN and DORMANT. 
A privileged user can install a task. Because memory is required 
for each task entered into the STD, the number of installed tasks 
Should be minimized. 


To remove a task from the STD, use the REMOVE command, which 
is privileged. 


In Example 8-2, a task image file called PROGRAM.TSK is’ used 
to show how to install a task, run it and then remove it from the 
STD. This task accepts one line of input from the terminal. It 


then changes the input line from uppercase characters to lower- 
case. The new line is then output to the terminal. 


@ “INSTALL/PRIORITY!75 PROGRAM. TSK 
=SHOW TASKSIPROGRA/ INSTALLED 


FROGRA 01 GEN 75, 00001700 NRO?-01321644 
@ “INSTALL/TASK NAME! JIM PROGRAM, TSK 

>SHOW TASKS! JIM/INSTALLED 

JIM O14 GEN 50. 00001700 DROt-01321644 
© VINSTALL/TASK-NAME?...JIM PROGRAM. TSN 

SHOW TASKS! JIM/INSTALLED 

JIM 4 GEN 50, 00001700 NROt-01321644 

SHOW TASKS!.+ HIM/INSTALLLALAEDAAA\ 

TAS -- Task mot in system 
@ =sHow TASKS!,,.JIM/INSTALLED 

veo JIM O14 GEN 50, 00001700 IiROt-01321644 
© =RuN JIM 

ABCDEFGHIJKL 

abedefgshiJkl 
@ -s1n 

ABCDEFGHIJKL 

abedefshidkl 
@ RUN PROGRA 


NOW IS THE TIME FOR ALL GOOD MEN TO COME TO THE AID OF THEIR FARTY. 
now is the time for 211 good men to come to the aid of their rarty, 


© =REMOVE JIM 
REMOVE .o + JIM 
REMOVE FROGRA 


Example 8-2 Samples of Installing a Task 
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Notes on Example 8-2 


The following comments are keyed to the example. 


The task image from the file named PROGRAM.TSK is 
installed with a priority of 75. The task name, by 
default, the first six characters of the task image file 
name. The SHOW TASKS command shows that the task will be 
loaded into partition GEN, has a priority of 75, and_ the 
disk address of the image file is DR@:-@1321644. To run 
the program, use the name PROGRA. 


The same task is installed again, with a task name of JIM. 
The priority defaults to the priority with which the task 
was built. To run the program, use the name JIM. 


In this case, the task is installed with the name ...JIM. 
This makes the task MCR spawnable. An MCR spawnable task 
is one that can be run by issuing just the last’ three 
characters of the task name. The RUN command is not used 
to invoke the task, as you will see in a later example. 


Notice that SHOW TASK shows a task name of ...JIM. At 
this point in time, there are three entries in the STD, 
all pointing to the same task image file. We can run the 
task in three different ways. 


To run an installed task that has not been installed as 
MCR spawnable, you must use the RUN command. [In this 
example, type RUN JIM. The task waits for you to. enter 
the string of characters. After a carriage return, the 
task converts the string to lowercase and outputs it _ to 
the terminal. The job is complete. Whenever you want to 
run the task again, you must say RUN JIM. There is no 
need to reinstall the task. 


This is an example of invoking an MCR spawnable task. You 
do not have to use the RUN command. MCR utilities are 
invoked in this manner. For example, PIP, the Peripheral 


Interchange Program, is invoked by typing PIP. Its task 
name is ...PIP. 


This shows how to invoke the task that was installed in 


note 1 above, uSing the first six letters of the task 
name. 
This shows how to remove the entries from the STD. After 


their removal, the task's states return to UNKNOWN. 
Trying to run a removed task would result in the error 
message: 


H##H##INS--Lile not found. 
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RUNNING A TASK 
Tasks can be scheduled to run: 
- Immediately 
- At a specific time of day 
- At some time interval from now 


- Repeatedly, at a time interval synchronized on the next 
hour, minute, Second or tick. (A "tick" is one pulse from 
the system clock. Usually, the system clock is 
synchronized with the ac line frequency.) 


Running Tasks Immediately 


Use the following format to run Uninstalled tasks 
immediately: 


RUN filename 
RUN Sfilename 


All tasks must be installed to run on the system. Therefore, this 
form of the RUN command does an automatic Install-—-Run-Remove. 
Note that the command requires a file name, not a task name. The 
$ in the second example above is a short form representation for 
the System UFD (M systems) or the System and Library UICS (M-PLUS 
systems). The system will run the task located in the system UFD 
rather than one located in the user's default UFD. 


Installed Tasks 


Installed tasks can be invoked in two ways. If they are MCR 
spawnable tasks, invoke them by issuing the three character name 
derived from the last three characters of the task name. For 
instance, under MCR, the Compare program that compares two ASCII 
files is invoked by typing CMP. Its task name is ...CMP. 
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All other installed tasks are invoked using the following 
format: 


RUN taskname 
RUN Staskname 


Note that the command requires a task name. The S$, once again, 
means to look on the System UIC (and the library UIC on M-PLUS 
systems) for the task image file. 


Tasks Scheduled to Run Later 


Suppose you wish to run a task during nonprime time hours 
when you are not at work. You can do that using the RUN command, 
provided that the task is installed and you are a privileged user. 


When you schedule a task to run at a later time, an entry is 
made in the system clock queue. The clock queue is a list of 
tasks that are waiting for time to expire before they are to. run. 
This queue is checked frequently for tasks whose time has expired 
and are, therefore, to be activated. 


To observe what jobs are in the queue, the SHOW CLOCK QUEUE 
command will give information regarding the task. To remove a 
task from this queue, you must issue the CANCEL command. 


In the following examples, the commands show how to run a 


task at a specific time, a delayed time or on an interval time 
basis. 


>RUN/SCHEDULE: 11:38:88 BATCHRUN 
>RUN/DELAY:1@S VIPROG 
>RUN/ INTERVAL: 10M EXERCISER 


In the first example, an entry is made in the clock queue to 
run the task BATCHRUN at 11:38. This is an example of running a 
task at a specific time of day. 


In the second example, the command specifies that VIPPROG 
Should be run ten seconds from the time you issue the RUN command. 


In the third example, the command specifies that the task 
EXERCISER should run every ten minutes. 
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LEARNING ACTIVITIES 


1. READ the following sections in the 
RSX-11M/M-PLUS Command Language Manual. 


e Chapter 7, Running Tasks 


- Section 7.1, Task Installation 
and Execution 


- Section 7.2, Introduction to’ the 
RUN command 


- Section 7.3, ABORT 

- Section 7.5, CANCEL 

- Section 7.8, INSTALL 

- Section 7.9, REMOVE 

- Section 7.12.3, SHOW TASKS 

- Section 7.12.5, SHOW CLOCK QUEUE 


2. DO Written Exercises 14 through 22 for 
this module. 
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LIBRARIES 


INTRODUCTION 


In this module you will learn how to create, maintain and use 
libraries. 


A library file is a direct access file containing a number of 
modules, usually of the same type. Users can collect often used 


Subroutines and macro definitions for eaSe of use and faster 
access during program development. 


OBJECTIVES 


To use libraries effectively, a user must be able to: 
l. Create libraries 

2. Maintain libraries 

3. Use libraries during program development 


4. Use libraries to collect files together 


RESOURCES 
1. RSX-11M/M-PLUS Command Language Manual 


2.e RSX-11M Utilities Manual 
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LIBRARIES 


Libraries are specially formatted files that contain a 
collection of associated files. For example, Object libraries 
contain object modules for program code that has been processed 
with a language translator. The object code could be for routines 
that are commonly used like a READ or WRITE RECORD routine. These 
object modules are grouped together into one file for the 
convenience of the user. You save program development time by 
using code that has already been developed and debugged. 


These files are maintained by a task called the Librarian. 
As the files are specially formatted for quick access and space 
saving, they cannot be displayed by using the DCL TYPE command. 
You must use the Librarian task to display the contents of a 
library file. There are three types of libraries: 


- Macro Source libraries 
- Object libraries 


- Universal libraries 


Macro Source libraries contain macro definitions written in 
the MACRO-11 language. They are Source statements. You use these 
libraries as input files when assembling them as MACRO-11 Source 
files. 


Object libraries. contain object modules. Object modules are 
the output from a language translator (like FORTRAN, COBOL, 
MACRO-11 Assembler). Before being placed in the library, the code 
has been used in a program and debugged. Object libraries are 
used at task-build time. 


Universal libraries are general-use libraries. They may 
contain text files, indirect command files or whatever you wish to 
place in them. They can be used merely as a repository for files, 
or aS in the case of indirect command files, as a central file for 
frequently used command files. 


There are many DIGITAL-supplied System libraries available, 
and the user may create his own special libraries. 


Benefits of Using Libraries 


The greatest benefit of libraries comes from Sharing code 
that has already been developed and debugged. Development costs 
are reduced when a programmer uses existing code. 
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Second, the MACRO-l11 Assembler and the Task Builder 
automatically search the System library. After processing all the 
input files, both tasks search a System library for any unresolved 
references. The System library specification is not included in 
the input command line. User libraries, which may also be used 
with both of these tasks, however, are not automatically searched. 
Their file specifications must be included in the input command 
line. 


Finally, having all modules in the same location saves’ time 
and overhead. Control can be applied to libraries; this assures 
that the latest version of a routine is being’ used. Only one 
entry for each module can be placed ina library. If a user 
wishes to have other versions of a routine maintained in a 
library, he must insert them with a different module name, or 
place them in another library. 


Library File Format 


All library files have the same format, as in Figure 9-l. 


LIBRARY HEADER 
ENTRY POINT TABLE 


MODULE NAME TABLE 
MNT 


MODULE #1 HEADER 


MODULE #1 


SYSLIB.OLB 


MODULE #N HEADER 


MODULE #N 


m 
m°) 


e 
e 
e 
r 
e 
AVAILABLE SPACE 
e 
° 
e 
° 
e 


Figure 9-1 Library File Format 
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Notes on Figure 9-1 


The following comments are keyed to the figure. 


Library Header 


This section contains information on the current library 
status including the date and time of the last addition, 
the number of Entry Point Table entries, the number of 
Module Name Table entries, the amount of available space, 
and the number of logically deleted bytes. For Universal 
libraries only, the default file type is kept in the 
header. 


Entry Point Table 


The Entry Point Table is used only with Object libraries. 
It is an alphabetic list of all the entry points in all 
the object modules in the library. 


An entry point is an address within a piece of code 
to which a program can transfer control such as: 


- a global label in MACRO 
- a subroutine 

- a function 

- block data 


This table is used to locate a piece of code in the 
library, when a request is made with the entry point name. 


See Table 9-1 for the source of the Entry Point Table 
name. 


Module Name Table 

The Module Name Table contains the name of every module in 
the library. It is used to find the module in the 
library. See Table 9-1 for the source of the Module Name 
Table entry. 


Header and module body for every module inserted into’ the 
library 


Space available 


Total library size set at creation time. If space 
exhausted, library must be rebuilt. 
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Table 9-1 Sources of EPT, MNT Entries Used in 
Creating a Library File 


LEARNING ACTIVITIES 


1. READ the following sections in Chapter 196 
of the RSX-11M/M-PLUS Utilities Manual: 


° AG Format of the Library File 
e 19.2, LBR Restrictions 
2. READ Section 6.3, Library, in Chapter 6 


of the RSX-11M/M-PLUS Command Language 


Manual. 


3. DO Written Exercises 1 through 4 for this 
module. 
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Macro Libraries 


Figure 9-2 is an example of the type of information stored in 
a Macro library. There are three macro definitions shown here, 
ALUNSS, CALL, and EXITSC. Each macro consists of all the 
instructions between the .MACRO and the .ENDM statements, and is 
written in MACRO-11 assembly language. Each of these was 
developed and tested before it was put into the library. 


The format of the Macro library consists of the library 
header, and the Module Name Table (MNT), followed by a module 
header and module for each macro definition. 


The module header contains information regarding the module 
itself. The size of the module, itsS status, and the date the 
module was inserted is stored here. For more detailed information 
regarding the module header format, refer to the RSX-~11M/M-PLUS 
Utilities Manual. 


The default file type for a Macro library is  .MLB. The 
System Macro library is RSXMAC.SML, and is located on LB:[{1,1l]. 
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USERMAC.MLB 


RSXMAC.SML 


ALUN$S —LUN,DA,DU,ERR 


MCALL MOV$,DIR$ 
Nove DU 
Movs DA 
MOV$ LUN 
MOV (PC+,—(SP) 
.BYTE 7,4 
DIR$ ,ERR 


ALUN$S 


ALUN$S HEADER 


ALUN$S 
CALL HEADER 
CALL 


EXIT$C HEADER y 


EXIT$C PSCT,ERR 
EXIT$C EXIT$,DIR$ 
$$$GLB 
$DPB$$ 
FREE SPACE 


PSCT 
#$$$,ERR 


EXIT$C 


TK-7488 


Figure 9-2 A Macro Library 
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Object Libraries 
Figure 9-3 shows the format of an Object library. 


An object module is difficult to visualize as it is not in 
human-readable form. Each object module contains instructions in 
object code. Each requires linking before it can be run. 


In the figure, there are three object modules in the library: 
ARITH, CLOSE and WRITE. ARITH has two entry points, $DIV:: and 
SMUL::. CLOSE and WRITE have one each, .CLOSE:: and .WRITE::. 
Notice that the EPT has an entry for each entry point in the 
library, and a pointer to the header of the respective object 
module, where it can be located. The Object library is the only 
one of the three library types to use the Entry Point Table (EPT). 


Entry points tell where a program will transfer control when the 
program executes. 


The default file type for an Object library is .OLB. The 
System Object library is LB:[1,l1]SYSLIB.OLB. After processing all 
the input files, the Task Builder searches through this’ library 
for any unresolved references. 


The Task Builder is able to search an Object library in two 
ways. The first way is when it tries to resolve unsatisfied 
references on global symbols. The global symbol is looked for in 
the Entry Point Table. The second way is when a module name has 
been specified with the /LIBRARY/INCLUDE qualifier of the LINK 
command. In both cases, when the module is found, the Task 


Builder extracts the complete module and includes it in the task 
image file. 
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SYSLIB.OLB 


LIB HEADER 


SYSLIB.OLB 


ARITH HEADER 
$DIV:: 
$MUL:: 


CLOSE HEADER 


USER.OLB 


Ut 


WRITE HEADR 


-WRITE:: 


FREE SPACE 


@ OBJECT MODULES DERIVED FROM AN ASSEMBLER 
OR COMPILER 
OBJECT FILE FORMAT INCLUDES ENTRIES IN THE 
EPT. 


TK-7495 


Figure 9-3 Object Libraries 
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Universal Libraries 


Universal libraries have the same format as Macro libraries. 
Like the Macro library, however, the EPT is not used. Figure 9-4 
shows this format and the type of input that a Universal library 
may have. This particular library is a collection of indirect 
command files that can be executed directly from the library. 
They do not need to be extracted first. 


The Universal library can be used to collect listing files 
with their source and object files. This is one method of 
transporting a program package from one system to’ another. When 
transferring the file from one media to another, only one file 
needs to be specified in the copy operation. Universal libraries 
can be used to collect memoS on a certain topic, like your 
programming project. 


The default file type for Universal libraries is .ULB. 
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MYLIB.ULB 


LIB HEADER 


BACKUP STRTUP 
BUILD SYSLOG 
SHUTUP WHO 
STARTU 


SST 
a 


BACKUP HEADER 


BACKUP 


WHO HEADER 


FREE SPACE 


INDIRECT COMMAND 


» ENABLE SUBSTITUTION 
o TESTFILE TI: 
SETS Tl <FILSPC>[1,5] 


; TERMINAL ‘TI’ IS AT 
;'<SYDISK>’ ‘<SYUNIT>":’<UIC>’ 


ENTRIES INTO THE LIBRARY MAY BE OF A UNIVERSAL 
TYPE. THIS ONE CONTAINS INDIRECT COMMAND FILES. 


© LiBRARY FILE FORMAT - EPT IS NOT USED. 


TK-7490 


Figure 9-4 Universal Libraries 
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use. Table 9-2 


DIGITAL supplies many libraries for your 
libraries that are available. Not all will be present 
on LB:[{1,1] 


You may perform a directory command 
The most frequently used 


lists the 
Time 


on your system. 
to see which ones your system does have. 
libraries are RSXMAC.SML, SYSLIB.OLB and the FORTRAN Object 


System libraries. 


4 


ee 


DIGITAL-Supplied Libraries on LB:[1,1] 
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Using Macro Libraries 


Figure 9-5 illustrates how to use Macro libraries. 


MACRO.MAC SY: [305,303] 


LBR.TSK 


; LIBRARY 
.MACRO SAVE LIST 


ARP X,<LIST> 
MOV X,-(SP) 

-ENDR 

-ENDM SAVE 


PROG.MAC 


: ST: SAVE <RO,R1,R2, 
MCALL SAVE,EXIT$C ALPHA, OMEGA> 


MOV 
MACRO MOV 
ST: SAVE <RO,R1,R2, ASSEMBLER 


Mov 
ALPHA,OMEGA> MOV 


MOV 


EXIT$C 5 


> MACRO/LIST MYMAC/LIBRARY, PROG 


LB:[1,1] 


MACRO EXITS$C LBR.TSK 


LIBRARY 


TK-7489 


Figure 9-5 Using Macro Libraries 
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Notes on Figure 9-5 


The following comments are keyed to the figure. 


Using the Librarian, put the Macro source in a library. 


In this example, the Macro SAVE is added to the User 
library MYMAC.MLB. 


Reference the Macro in a source file. In a source 
program, PROG.MAC, reference is made to the SAVE macro. 
EXITSC is also referenced. 


Assemble the source referencing the library containing the 
Macro. The Macro Assembler searches MYMAC.MLB for the 
macro definition for SAVE and finding it expands’ the 
macro, making the proper symbol substitutions. The Macro 
EXITSC is not found in this library and remains 
unsatisfied. 


Previous to the assembly process, the System Macro 
library, RSXMAC.SML, was created using the Librarian. The 
Macro EXITSC is contained in this library. Once the 
assembler searches any User libraries specified in the 
MACRO command line, it turns to the System Macro library 
to resolve any other unsatisfied references. In this 
case, EXITSC is found, extracted from the library and 
included in the source program. The MACRO-11 Assembler 
searches the User library for unsatisfied references, then 
automatically searches the System Macro library, 
LB:[1,1]RSXMAC.SML. 
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Using Object Libraries 


The procedure for using Object libraries is similar to that 
of Macro libraries, however, their use occurs later in the program 
development process. 


>LIBRARY/CREATE MYLIB WRITE,READ 
WRITE.OBJ. 


SY: [305,303] 


LIBRARIAN MYLIB.OLB 


>LIBRARY/INSERT [1,1] SYSLIB CLOSE,OPEN 


CLOSE.OBJ 


LIBRARIAN 


>FORTRAN PROG 


PROG.FTN SY:[305,303] 


OPEN FILE 


DO | = 1,10 FORTRAN 
WRITE RECORD COMPILER 


CONTINUE 
CLOSE FILE 


>LINK/MAP PROG, MYLIB/LIBRARY 


SY :[305,303] LB: [1,1] 


TK-7505 


Figure 9-6 Using Object Libraries 
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Notes on Figure 9-6 


The following comments are keyed to the figure. 


A User Object library called MYLIB.OLB is created using 
the Librarian. Two object modules (WRITE, READ) contained 
in two object files (WRITE.OBJ and READ.OBJ) are placed in 
the library when it is created. 


The System Object library, SYSLIB.OLB, is modified to 
include two object modules (CLOSE and OPEN) which are 
contained in two object files (CLOSE.OBJ and OPEN.OBJ). 


In a source file, PROG.FTN, reference to three of those 
modules is made (OPEN, WRITE and CLOSE). The file is 
compiled. A listing file generated from the compile shows 
those three references as unsatisfied, as they are not 
defined within this source file. 


At link time, the User Object library, MYLIB.OLB, is 
supplied in the command line. The Task Builder reads this 
library first, searching for code for OPEN, WRITE and 
CLOSE. Only the code for WRITE is found, extracted and 
included in the Task Build from this library. The Task 
Builder then searches the SYSLIB.OLB for CLOSE and OPEN. 


Be careful in supplying library specifications in the LINK 
command line. If the User library contains object modules 
for CLOSE and OPEN, the Task Builder would extract these 
modules to satisfy the references to those symbols. If 
the desired code is in the System library, the results 
then are wrong. For a solution to the situation, read the 
DCL HELP provided on the /LIBRARY/INCLUDE qualifier to the 
LINK command, or refer to the /LB switch discussion in the 


RSX-11M/M-PLUS Task Builder Manual. 
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Using Universal Libraries 


When universal libraries are used as repositories for text 
files, you create them by uSing the Librarian and inserting the 
text modules into them. The module names will be taken from _ the 
input file name. You can then uSe the librarian commands to list 
the contents, extract or insert new modules. If the library is a 
collection of indirect command modules, a particular command 
module can be executed without extracting it from the library 
using the following command: 


>@MYLIB.CLB/LB:WHO (MCR command) 
In this example, the library file, MYLIB.CLB, is used with the /LB 


Switch to specify the indirect command module (WHO.CMD) to be 
executed. 


Universal libraries can also be accessed from a task by 
building that capability into the task in the following manner: 


- Build a Universal library containing the desired modules. 


- Develop your application program using SULA, a System 
library routine, to access the library. 


- Assemble/compile, task-build and run _ the application 
program. . 


For more information regarding SULA, refer to Appendix B of the 
IAS/RSX-11M System Library Routines Reference Manual. 


Creating/ Maintaining Libraries 

Table 9-3 lists operations using the Librarian. The DCL 
command is shown, along with a command example. Table 9-4 shows 
the equivalent MCR commands to accomplish the same operations. 


Table 9-5 lists CREATE command parameters and qualifiers, 
While Table 9-6 lists Librarian listing qualifiers. 
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Table 9-3 DCL Library Commands 


. ‘Creating a | New Library es : 


DCL Command >LIBRARY/< [:ARG] [ /QUALIFIE} 
DCL Example >LIBRARY/c! EATE/BLOCKS: 200. MYLIB_ 
Note . nee Table 9- 2) z 


BSPEC [INFILE(S]] _ 


Mating the Contents of a File” 
1 am] — SETBRARE/CEsn/ FUL MYLIB 
OU Bhs hea ane: Tae 9-6 


‘PILESPECIS] 
OGOUT.CMD — 


DCL Command — >LIBRARY/IN: 
DCL Example —_>LIBRARY/I 


DCL Command  >LIBRAR 
Bce ERonnre [SOT ERAR 


LDLIBSPEC | NEWLIBSPEC 
B2- 


DCL Command —>LIBRAR 
DCL Example >LIBRA 
Nore ee 
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Table 9-4 Equivalent MCR Library Commands 
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Table 9-5 CREATE Command Parameters and Qualifiers 
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LEARNING ACTIVITIES 


1. READ the following sections in Chapter 19 
of the RSX-11M/M-PLUS Utilities Manual: 


e 18.5.1, Compress Switch 
e 10.5.2, Create Switch 

e 19.5.3, Delete Switch 

e 10.5.7, Extract Switch 


e 19.5.8, Insert Switch for Object, 
Macro Libraries 


e 18.5.9, Insert Switch for Universal 
Libraries 


e 1@.5.19, List Switches 


e 16.5.12, Replace Switch for Object, 
Macro Libraries 


e 19@.5.13, Replace Switch for Universal 
Libraries 


2. DO Written Exercises 5 through 11 for 
this module. 
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Example 9-1 


LIBRARIES 


9-1 and 9-2 show some frequently used 


*“LIBRARY/LIST LRi Ci» lIRSXMAC.SML 


Directory of file RSXMAC.SML#121 

Macro library created by? LBR V06.00 

Last insert occurred 23-AUG-81 at 13204321 
MNT entries allocated! 312% Available? 93 
EPT entries alloceted: OF Available: oO 
File srace available? 01193 words 
Recoverable deleted srace? 00179 words 


ABRT$ 
ABRTSC 
ABRT$S 
AFF S$ 
ALTPS$ 
ALTFSC 
ALTPS$S 
ALUNS 
ALUNSC 
ALUNSS 
ASTX$ 
ASTXS$C 
ASTX$S 
ATRGS 
ATRGSC 
ATRGSS 
BDOFFS 
CALL 
CALLR 


™, 


*LIBRARY/LIST/FULL LESCLl,1IRSXMAC.SML 
Directory of file RSXMAC.SML#121 

Macro library created by! LBR V06.00 
Last insert occurred 23-AUG-81 at 13:04:21 
MNT entries allocated: 5123 Available: 973 
EFT entries gllocated: OF Available: 0 
File seace available? 01193 words 
Recoverable deleted srace? 00179 words 
ABRT$ $izei00096 Inserted! 7-AUG-81 
ABRTSC Sizei00096 Inserted: 7-AUG-S81 
ABRT$S Sizei:00068 Inserted? 7-AUG-81 

AFF $ Sizei00101 Inserted!7-AUG-81 
ALTPS$ Sizei00112 Inserted! 7-AUG-81 
ALTFSC Sizei00104 Inserted!7-AUG-B1 


ALTF$S Sizei:00078 Inserted: 7-AUG-81 


LIBRARY 


Obtaining Library Directories (Sheet 1 of 2) 
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© cLIBRARY/LIST/NAMES LEiCirs1ISYSLIB.OLE 
Directory of file SYSLIE.OLBs33 
ObJect module library created but LBR V06.00 
Last insert occurred 11-AUG-81 st 10319325 
MNT entries allocated: 7683 Available: 524 
EPT entries allocated: 23045 Available: 964 
File sreace avzilable! 00675 words 
*X Modules ALERR 


SALERR 


¥k ModulesALSCT 


ALSCT 


KK Module: ALTFRI 
ALTFRI 


xX Module? ANSPAL 


KX Modules ARITH 


$DIV $MUL 


Example 9-1 Obtaining Library Directories (Sheet 2 of 2) 
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Notes on Example 9-1 


The following comments are keyed to the example. 


To list the contents of a library you use the /LIST 
qualifier on the LIBRARY command. The library, file 
specification is given as a parameter. The output from 
issuing this command consists of a = short statistical 
section and then the list of names of the modules 
contained in the library. This example lists the contents 
of the System Macro library. The module names are listed 
in ascending order. A <CTRL/O> was typed before the 
output was finished, so this is not a complete list. 


By using the /FULL qualifier, additional information is 
provided on the modules. Their size and the date they 
were inserted into the library are displayed. 


To obtain the entry point names in an object module, the 
/NAMES qualifier is used. The entry point name appears 
after the module name. In this example, module ARITH has 
two entry points, SDIV and SMUL. 
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s 


@ cLIBRARY/CREATE/MACRO MYLIE FILES 


© >LIBRARY/DELETE MYLIE.MLB MVE$>OFFS 
Modules deleted? 
MVES$ 
OFF$ 


© 2LIBRARY/REFLACE MYLIB.NLE FILES 
Module "CALL °* rerlaced 


Module ‘QIOW$ * rerlaced 


Module “EXIT$C" rerlaced 


@ -LIBRARY/LIST MYLIB.HLE 


Directory of file MYLIE-MLEs1 

Macro library created byt LBR V06.00 

Last insert occurred 3-SEF-81 at 14354340 
MNT entries allocated’: 2543 Available: 251 
EPT entries allocated? 03 Available: 0 
File space available} 23877 words 


CALL 
EXIT$C 
MVB$ 
OFFS 
QIOWs 


Example 9-2 Commands to Create a Library and 
Delete Modules from that Library 
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Notes on Example 9-2 


This is an example of the command you issue to create a 
library. If you do not specify the libary type, the 
Librarian assumes an Object library. In this case, the 
Librarian creates a Macro library with a file name of 
MYLIB.MLB. FILES is the name of the input object file 
(FILES.OBJ) containing the modules to be inserted into the 
library. The size of the resulting library file will be 
188 blocks, with space in the MNT for 256 entries. These 
are the default values for creating a Macro library (See 
Table 9-5). If these values are not suitable for your 


library, you must supply the proper values with the 
/CREATE qualifier. 


Listing the contents of the library shows that there are 
five macro definition modules in the library: CALL, 
EXITSC, MVBS, OFFS and QIOWS. 


To delete modules from a library, a list of module names 
is supplied after the library file specification. When 
you delete a module from the library, it is only logically 
deleted from the file. The space in which it resides is 
not released for use until the file is compressed. 
Compressing a library file removes deleted modules, and 
compresses the remaining modules toward the beginning of 
the file. Free space is then generated at the end of a 
file for inserting new modules. 


When you want to place a newer version of a module in the 
library, you must use the /REPLACE qualifier. The input 
file, FILES.OBJ, contains newer versions of CALL, QIOWS 
and EXITSC that will replace the respective modules in the 
library. 
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ADVANCED MAINTENANCE OPERATIONS 


INTRODUCTION 


You have studied some of the moSt common operations involving 
files and storage volumes. We will now look at some of the more 
advanced operations. 


Until now, it was assumed that all the files you would access 
would be on your default volume, or on some other volume defined 
by your system manager as public (i.e., available to anyone). For 
reasons of security or convenience, you may instead wish to access 
your files on a private volume. Or, you may wish to set up a 
Shareable volume that certain chosen usersS can access. This 
module shows you how to set up, use and maintain private and 
shareable volumes. 

It was also assumed that you would deal solely with a_ single 
RSX-11M and/or RSX-11M-PLUS system. Transferring files to another 
operating system, or between different RSX-11M/M-PLUS systems, 
involves access to volumes with a different format than FILES-1l. 


These volumes are called foreign volumes. Accessing foreign 
volumes is alSo covered in this module. 


OBJECTIVES 


l. Prepare and maintain private volumes for file storage. 


2. Use the file transfer utility to transfer files between 
computer systems and convert file formats. 


3. Print files and control the print queue. 
4. Use the dump utility to inspect the contents of a file. 


5. Use the compare utility to segregate the differences 
between two ASCII files. 


RESOURCES 


1. RSX-11M/M-PLUS Utilities Manual 


2. RSX-11M/M-PLUS Command Language Manual 
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VOLUME MAINTENANCE 


Up until now, you have been using a volume that was 
initialized, maintained, and backed up by someone else, most 
likely your system manager. However, the opportunity may arise 
when you will want to use a private volume to store files for 
special applications, or for transferring files to other computing 
systems. To do this, you must’ know about the utility tasks 
available for maintaining a volume. In this section you will 
learn about the volume maintenance utilities (FMT, BAD, BRU, DSC, 
VFY), a more detailed understanding of the file Structure, and 
device and volume accessibility. 


Device Types 


There are two types of hardware devices that the operating 
system must control: record-oriented and file-structured devices. 


Record-oriented devices, like line printers, terminals and 
card readers, process records one at a time. For example, the 
operating system transfers data to the line printer 132 characters 
at a time. After the transmission completes, there is no way to 
access that record again. The printer does not collect each of 
these records into ae file. Storage of these records occurs 
off-line, on a piece of paper. 


On file-structured devices like disk drives, magnetic tape 
drives, and DECtape drives, the operating system is able to 
collect records into a file and store them for future’ use. One 
Structure is used for storing and retrieving files on all 
file-structured devices. 
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FILES-11 Volume Structure 


FILES-11 is a software system that creates and maintains’ the 
file structure on disks, DECtape and floppy disks. It uses a two 
level directory structure to organize and maintain files on a 
volume. The first level structure is the Master File Directory 
(MFD). The second level is the User File Directory (UFD). This 
structure is maintained by the Ancillary Control Processor task, 
FI1IACP, part of the FILES-11 software system. It performs’ the 
following tasks: 


- Locates logical blocks on disk 

- Allocates storage for files 

~- Reads and writes file attributes 

- Controls access to files 

- Performs MOUNT and DISMOUNT operations’ for FILES-11 


volumes 


To locate a file on a volume, the system must first check the 
MFD, ([(@,8@]@@@0@@.DIR), to see if the UFD specified in the file 
specification actually exists on the volume. If there is no entry 
in the MFD for the specified UFD, the system returns an error 
message. If there is an entry, the system then looks at_ the 


directory file for the specified UFD, to see if the requested file 
actually exists. 
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Volume Files 


A new volume must be prepared before the operating system can 
access it. One of the preparation steps is to establish the 
FILES-11 structure by creating the five standard system files that 
must be present on each volume. You do this with the INITIALIZE 
command, which creates the five files listed in Figure 1@-1l under 
the special UFD [@,®@]. 


Once these files are present on the volume, you can use the 
CREATE/DIRECTORY command to create any needed UFD. 


Once the UFDs are established, files can be created under 
each by uSing the editor, copying files from another volume, or by 
program execution. 


File Name Contents 
@ INDEXF.sys Index File 
@ BITMAP.Sys Storage-allocation file 
© BADBLK.SsyS Bad block file 
@ %00000.DIR Master File Directory (MFD) 
@ cORIMG.SyYS System Checkpoint File 


BITMAP.SYS 
BADBLK.SYS 


000000.DIR 


TK-7486 


Figure 18-1 FILES-11 Standard System Files Found on Every Volume 
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Index Files 


The first system file in Figure 1@-1 is the index file, the 
most important file on the _ volume. It is the master key for 
accessing any file. 


Figure 18-3 shows the format of the index file, and contains 
the following information: 


@e Volume Information (Home Block) 


- Volume Name 

- Device Type 

- Volume Owner's UIC 

- Volume Protection Code 
- Default File Protection 


e File Header Blocks 


- One for each file on volume 
- 256 words long 
- Contains: 


File ID number to indicate which file header to 
use to locate the file on the volume 


File sequence number to verify correct header 


Every file is made up of two parts, as shown in Figure 19-2. 
The body of the file, which can be stored anywhere on the disk 
volume, contains the data. A system, called INDEXF.SYS, contains 
the second part of a file, the file header. Every file on the 
volume has a header that the system uses to locate the body of the 
file. Before locating any file on the volume, the INDEXF.SYS file 
must be read to obtain the necessary information to locate the 
body of the file. 


Figure 19-3 shows the format of the INDEXF.SYS file. Notice 
that headers exist for the five system files that must be present 


on every volume, the MFD, all UFDs, and user files present on the 
volume. . 
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MESSAGE.TXT 


HEADER 


MESSAG.T XT 
VERSION=2 


BODY 


DISK ADDR:5003 
SEG #1 


DISK ADDR:5104 
SEG #2 


TK-7498 


Figure 18-2 The Two Parts of a File 
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[0,0]INDEXF.SYS 


HEADER-UFD #N 
HEADER-USER FILE #1 
HEADER-USER FILE #N 


TK-7502 


Figure 18-3 Index File Format 
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Bitmap Files 


The second system file, BITMAP.SYS, is the file the operating 
system uses to control available space on the volume. Each volume 
is divided into blocks where the operating system can store 
information. In the bitmap file, there is one bit for each block 
on the volume. When a block is in use, its representative bit is 
set to a "1". If it is not in use, the bit is set to "@". The 
operating system checks the BITMAP.SYS file to find available 
space for creating and extending files, and to mark the bit for 
blocks that become available. 


Bad Block File - All blocks not readable by the operating system 
are allocated to the file called BADBLK.SYS. The system task, 
BAD, run when preparing a volume for use, provides the information 
for this file. Allocating bad blocks to this file makes them 
unavailable, and decreases the frequency of I/O read and write 
errors. 


Core Image File - This file, CORIMG.SYS, is set up to_ provide 
space for system checkpointing. Every volume has the capability 
of having system checkpoint space where checkpointed tasks can be 
written. To activate this area, a privileged user must use the 
SET DEVICE/CHECKPOINT FILE command to allocate space to this file. 


Directory Files - The two types of directory files that are 
present on a volume contain entries for UFDs or user files. Each 
entry in the file contains a file name, a file header number, and 
a file sequence number. 


On a Single user volume, (Figure 19-4), only one type of 
directory file is needed, the Master File Directory (MFD). 


On multiuser volumes, (Figure 19-5) you must have one MFD and 


one UFD for each volume _ user. You use the CREATE/DIRECTORY 
command or the ACNTS program to establish the UFDs. 


387 


ADVANCED MAINTENANCE OPERATIONS 


000000.DiR 
MASTER 


FILE 
DIRECTORY 
[0,0] 


BITMAP.SYS 
BADBLK.SYS 


000000. DIR 


a 


TK-7500 


Figure 19-4 Directory Structure for Single-User Volume 


000000.DIR 


MASTER 
FILE 
DIRECTORY 


<r aii 

BITMAP.SYS 

BADBLK.SYS 

000000.DIR 

FILE 
001001.DIR DIRECTORY [5,10] [305,303] 
[1,1] 

eae tlk 001001.DIR  _005010.DIR 305303.DIR 

305303.DIR 


FILE A FILE B 


TK-7499 


Figure 18-5 Directory Structure for Multiuser Volume 
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ANSI Magnetic Tape Structure 


The structure used for storing data on magnetic tape varies 
according to the application. Generally, on RSX-11M/M-PLUS 
systems, the ANSI Magnetic Tape structure is used to write data on 
the medium. This structure, shown in Figure 19-6, is maintained 
by the Magnetic Tape Ancilliary Control Processor task (MTACP). 
Notice that it does not have the MFD, UFD structure. Files are 
stored sequentially on the tape, with the file header preceding 
the body of the file. The file header contains the following 
information: 


~ file name and extension 
- file section number 

- file sequence number 

- creation date 


- record format 


Other Tape Formats 


Utilities such as BRU, DSC, and FLX each have their own 
magnetic tape formats for efficient processing. A tape created by 
a particular utility can only be processed by that utility. It is 
important to remember how you create a magnetic tape so that 
information can be retrieved by using the proper utility. 
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BEGINNING OF 
TAPE MARKER 


BOT 


VOLUME LABEL 
(VOL 1) 


FILE HEADER LABELS 
HDR1, HDR2 


TAPE MARK (TM) 


FILE BODY 


TAPE MARK (TM) 


FILE TRAILER LABELS 
(EOF 1,EOF2,EOV1,EOV2) 


TAPE MARK (TM) 
TAPE MARK (TM) 


END OF TAPE (EOT) 
MARKER 


TK-7503 


Figure 18-6 ANSI Magnetic Tape Structure 
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Device and Volume Accessibility 


Volumes and the devices on which they reside are available to 
the user depending upon characteristics established for them. Not 
all volumes or all devices are available for everyone's’ use. 
Accessibility is established in two ways: device ownership and 
volume accessibility. 


Device Ownership 


Devices on the system are declared to be public, private or 
unowned, aS in Table 19-1. 


A public device is one established for use by all users. The 
SET DEVICE command, which is privileged, declares a device to be 
public. When a device is set to public, the volume mounted on the 
device is automatically mounted as public. This allows any user 
access to the data stored on that volume. 


A private device is one for use by the person who allocates 
it. 


Any device that has not been set public, private, or mounted 
is known aS an unowned device. 


Once the device attributes are established, a user can _ grant 
access to the volume mounted on the device, as shown in Table 
18-2. If the device is public, no further command is’ neccessary. 
However, to establish the volume as private or shareable, use the 
MOUNT command. 


Table 19-1 Device Ownership 
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Mounting a Volume 


Before a disk or magnetic tape volume can be used on a 
device, the operating system must know that it is there. Just 
physically mounting a disk volume on the drive is not enough. You 
must logically inform the operating system by using the MOUNT 
command. This command establishes the software connection between 
the operating system and the volume. 


The operating system also must know if the structure of the 


volume information is in FILES-1l format. If not, you mount it as 
FOREIGN. 


The MOUNT command also establishes who may have volume 
access. Table 18-2 indicates how to establish a volume as public, 
Private or shareable. 


Table 18-2 Volume Accessibility 


ee : sgucunaeramee sean 
ge a ee 
co a ce 


a 


secrngeser we 
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Bee, 


a 
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ae 
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Preparing a Disk Volume for Use 
Physical Formatting 

Before you can use a disk pack on the system for the first 
time, it must be properly initialized. Initialization of the pack 
is a two step process. The first step is to physically format the 
disk. The system task, FMT, formats the disk into blocks, the 
smallest unit of writing area allocated to a file. The task, BAD, 
is then run to determine which blocks’ on the disk cannot be 
written to, or read properly. The following steps accomplish the 
physical formatting of the disk: 

e Allocate disk drive using ALLOCATE/DEVICE command 

e Physically load disk pack on drive 

e Logically mount pack using MOUNT/FOREIGN command 

e Run utility formatter task (FMT) 

MCR FMT 
e Run bad block task (BAD) 


MCR BAD 


FILES-11 Initialization 


The second step in the initialization process is to set up 
the FILES-11 volume structure, which includes the creation of the 
five system files that must be present on the’ volume. Once the 
FILES-1l structure is there, you can create UFDs for those who 
require them. Example 18-1 shows the complete process. Once the 
following steps are done, the disk volume is ready for use: 


e Use INITIALIZE command to set up FILES-11 volume structure 


e Logically DISMOUNT the volume and REMOUNT it with volume 
label name 


e Create UFDs with CREATE/DIRECTORY command 
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Preparing a Magnetic Tape Volume for Use 

To prepare a magnetic tape for use requires that an ANSI 
standard volume label be written on the tape, followed by a dummy 
file. Tape initialization requires no physical formatting. The 
following steps prepare a magnetic tape for use. An actual tape 
initialization process is shown in Example 10-2. 

e Allocate magnetic tape unit using ALLOCATE/DEVICE command 

e Physically mount the tape on the drive 


e Logically mount the tape using MOUNT/FOREIGN command 


e Use INITIALIZE command to prepare magnetic tape in ANSI 
Standard format 


e Logically DISMOUNT volume and REMOUNT it with volume label 
name 
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>ALLOCATE DK2; 
>MOUNT/FOREIGN DK2: USER 
>MCR FMT 

FMT>DK2: 


KK WARNING - Data will be lost on DK2: x 
Continue? CY OR NI: Y 

Stary formatting 

Start verification 

Oreration complete 


FMTS 2 

>MCR BAD 

BADAIK 23 

BAD -- DK2: Total bad blocks= 0. 

BAD>*Z 

>INIFIALIZE DK2: USER 

>DISMOUNT DK23 

DMO -- TT56: dismounted from DK2? 4KK Final dismount initiated **x 
>MOUNT DK2? USER 

SOIR BDR2:00s0] 


Directory DK23C0r0) 
15-SEP-81 11333 


INDEXF .SYS#1 155. 15-SEP-81 11:33 
BITMAP.SYS31 3. 15-SEP-81 11:33 
BADBLK.SYS#1 1. 15-SEP-81 11:33 
000000. DIR#1 1. 15-SEP-81 11°33 
CORIMG.SYS#1 O- 15-SEP-81 11:33 


Total of 160./160. blocks in 5S. files 
> 


> 
>CREATE/DIRECTORY DK2! £305%303 
>DIR BRAC 305% 303) 


DIR -- No such file(s) 


>LO 

DMO -- TTS63 dismounted from DK23 KKX Final dismount initiated kxx 
Have 2 Good Mornings 

eile aa 11236 TT56? lossed off QUASAR 


Example 18-1 Preparing a Disk Volume 


Vv 


>ALLOCATE MMO: 
>MOUNT/FOREIGN MMO: USER 
>INITIALIZE MMO’ USER 
>DISMOUNT MMO; 


DMO -- TTS63: dismounted from MMO?’ ¥XX Final dismount initiated xKx*xk 
? 


ag 


Example 19-2 Preparing a Magnetic Tape Volume 
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Backing Up a Volume 


For critical files that you cannot afford to lose, it makes 
sense to routinely backup the files on another volume. Backing up 
a volume means making a duplicate copy of it, and storing the copy 
in a protected place. Then, if needed, you can restore the files 
from the backup volume. 


There are a number of ways to backup files, or a complete 
volume. The simplest way is to use the COPY command to copy files 
to another volume. This is sufficient when backing up ae few 
files, but is quite cumbersome if backing up a complete volume. 
BRU and DSC are two utilities that exist to backup volumes. Each 
has its benefits. 


Backup and Restore Utility (BRU) 


The Backup and Restore Utility (BRU) is used for FILES-11 
volumes. The output volume can be either a disk or magnetic tape. 
In addition to performing the backup, BRU will initialize the disk 
and run BAD to locate bad blocks. With this utility you can 
backup Selected files, or a complete volume by file specification, 
date or time. 


BRU writes data to the magnetic tape in its own tape format. 
Therefore, BRU must be used to restore data from a BRU backup 
tape. 


Table 198-3 lists the various backup command qualifiers. 
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Command Format 


>BACKUP/SAVE__SET:VIPPROGS DB1:** MM1: 


Command to invoke BRU to back up a disk area 
Command qualifier 
Qualifier value 


Source device and file specification for files to be backed up 


Destination device 
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Table 18-3 Backup Command Qualifiers 


Sars 28g 


ee 


. S pee 
ee 


es 
tee 
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Disk Save and Compress Utility (DSC) 


The Disk Save and Compress Utility (DSC) is used to duplicate 
FILES-11 volumes using either disk-to-disk or disk-to-tape file 
transfers. DSC backs up and restores entire volumes, and in the 
process compresses files into contiguous blocks, making more space 
available. DSC also has its own output magnetic tape format, so 
DSC must be used to restore a tape that it creates. 


VERIFY (VFY) 


The VERIFY utility is used to maintain the FILES-11 
structure. It recaptures blocks marked as used but not belonging 
to a file. It searches for files in the index file that are not 
in any directory, as well as validates directories against the 
files they list. VERIFY requires that the volume to be _ verified 
be mounted as a FILES-11l1 device, and no other activity on the 
volume takes place. It is generally used after a system crash _ to 
ensure integrity of the structure, or if you suspect corruption on 
the volume. 
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LEARNING ACTIVITIES 


READ the following sections in the 


RSX-11M/M-PLUS Command Language Manual: 


e 5.1.3, Public, Shared, Private and 
Unowned Devices and Mounted Volumes 


e 5.1.4, How to Prepare a Scratch Disk 
for Use 


e 5.1.5, How to Prepare a Scratch ANSI 
Magnetic Tape for Use 


e 5.4, Allocate 

e 5.5, Deallocate 

e 5.6, Mount 

e 5.7, Dismount 

e 5.8, Initialize 

e 5.9, Backup 

e 5.10.2, Set Device 


READ the following in the RSX-11M/M-PLUS 


Utilities Manual: 


e Chapter 7, Backup and Restore Utility 
(BRU) 


e Chapter 8, Disk Save and Compress 
(DSC) 


e Chapter 5, Disk Volume Formatter 
(FMT) 


e Chapter 6, Bad Block Locator Utility 
(BAD) 


DO Written Exercises 1 through 11 for 
this module. 
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FILE MAINTENANCE 


Transferring Files Between Computer Systems 
File Transfer Program 


The File Transfer Program (FLX) transfers files from one 
volume to another. In addition, when the volume structures 
differ, FLX will convert the file to the output volume format. 
The following file conversions and transfers can be accomplished: 


e DOS-11 to FILES-11 volumes 

e FILES-11 to DOS-11 volumes 

e DOS-11 to DOS-11 volumes 

e FILES-11 to FILES-11 volumes 
e FILES-11 to RT-11 volumes 

e RT-11 to RT-11 volumes 


e RT-11 to FILES-11 volumes 


Figure 18-7 shows the different file structures used by three 
operating systems that run on PDP-1l hardware. RT-1ll uses a 
contiguous file storage structure. All blocks of a file are 
stored together on the disk. 


RSTS (DOS-11) uses a linked list structure. Each block is 
stored individually where space permits. A pointer to the next 
block in the file is stored with each block. 


On RSX-11M/M-PLUS, FILES-11 breaks up the file into Segments 
and stores the segments on the volume. A segment consists of one 
or more blocks. In the header of the file, a record is kept of 
the number of segments, the number of blocks in each segment, and 
the address location of the segment on the volume. 


In addition to this difference, there is a difference in the 
way text files, object files, and executable files are formatted 
on each operating system. For text files on RSX, the- record 
length is determined by a character count, which is stored in the 
first position of a string of characters that constitute the 
record. On RSTS and RT, the record length is determined by the 
<CR> <LF> that is stored at the end of a string of characters. 
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Each operating system formats and stores files differently. 
Therefore, the DCL COPY command which does a straight copy, cannot 
be used to transfer files from a volume initialized on one system, 
to one initialized on another system. 


FILE STRUCTURES 


FILE.TXT 


[wer [vee] 09] vou [ves 
andy ~N 
~ 
~ 


~~ 


~ 


[V8 1] vez] ves | veal v85 


CONTIGUOUS FILE STRUCTURE 


FILE.TXT 


[es [vee [ves [ve [vee 


LINKED LIST STRUCTURE 


FILES-I| 
FILE.TXT 


[er [owe [vee [var [oe 


INDEXF.SYS 


MAP-FILE STRUCTURE 


VB=VIRTUAL BLOCK 


TK-7494 


Figure 18-7 PDP-11 File Structures 
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Transfer Mode Switches 

There are three transfer modes (Table 19-5) that you may use: 

e@e Formatted ASCII 

e Formatted Binary 

e Image Mode 

Formated ASCII is used to embed the <CR> <LF> in text files 
when you are generating RSTS and RT output. Formatted binary is 
used to correctly format .OBJ, .STB, .BIN and .~LDA files for RSTS 


and RT output. Image mode is a straight copy with no changes for 
executable files and libraries. 


Command Format 


>FLX<RET> 
FLX >DK1:/RT=DKO:SYS1.MAC/RS 
eee wee 
2) 6 Oo 5 | 6) 


Command to invoke the file transfer program 
Output device 

A volume format, transfer mode or control switch 
Delimiter 


Input file and device specification 


A volume format, transfer mode, or control switch 
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Table 198-4 FLX Format Switches 
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Controlling a Print Queue 


When a device is frequently used, like the line printer, a 
method is needed to manage that device efficiently to ensure that 
it is readily available for use. A system task, the Queue 
Manager, iS reSponsible for managing such devices. Line printers, 
plotters, and hard-copy terminals being used as line printers’ are 
the kinds of devices the Queue Manager oversees. 


Once a device is under control of the Queue Manager, it can 
no longer be used in the usual manner. For example, when the line 
printer is under Queue Manager control, files cannot be sent 
directly to the line printer. Queue Manager commands must be used 
to process files. 


Figure 18-8 shows how the Queue Manager handles a line 
printer aS a Spooled device. The PRINT command indicates a file 
to be printed on the line printer. This command is passed to the 
Queue Manager for processing. A file called LB:[1,7]QUEUE.SYS 
contains an entry to indicate that a file is ready for printing. 
This part of the process is called spooling. The Queue Manager 
frequently checks the queue to see if there are any waiting jobs. 
If it finds one for the line printer, it checks if the line 
printer is available. If no job is printing, the Queue Manager 
Starts printing the file. This part of the process is called 
despooling. 


To enter a job into the print queue, you use the PRINT 
command. Examples are shown in Table 19-6. Once the job is in 
the queue, to alter job characteristics or to cancel a job, you 
must use the commands in Table 19-7 or 19-8. 
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THE QUEUE MANAGER 


FILE.TXT 


en ep ee 
SPOOLING DESPOOLING 
USE PRINT COMMAND TO MAKE USE QUEUE COMMANDS TO ALTER 
ENTRY IN THE QUEUE JOB ONCE !T HAS BEEN ENTERED IN THE 


QUEUE 


TK-7506 


Figure 19-8 The Queue Manager 
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Table 18-7 DCL Commands to Alter Print Queue 
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Table 19-8 Equivalent MCR Commands to Alter Print Queue 


BS 
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Looking at the Contents of a File 
File Dump Utility (DMP) 


In the course of program development, it is sometimes 
necessary to inspect the contents of a file. You may want to 
check the file format to ensure that it is correct. And if it is 
not correct, you would want to determine the spot where it was not 
formatted properly. The File Dump Utility (DMP) helps in 
uncovering such problems. 


DMP will dump a file in any one of the formats listed in 
Table 19-9. You must decide which format is suitable for your use 
and for the file. 


Figure 18-9 depicts how the DMP program can interpret sixteen 


bits of data. If a word contains the value as shown in the 
figure, the string of @s and 1s can be interpreted in many 
different ways. For example, interpreting the data as an octal 


word gives it the value of. 944124. Interpreting the data as octal 
bytes, the left byte value is 118, and the right byte value is 
124. Interpreting the data as two ASCII characters yields an H in 
the left byte, and a T in the right byte. Each of these 
interpretations could be correct depending upon the content= and 
purpose of the file. 


The DMP utility has two modes of operation: file mode and 
device mode. File mode requires that the volume on which the file 
is located be mounted as a FILES-1l volume. This mode dumps’' the 
virtual blocks of a file, and is used more frequently. Device 
mode is for dumping logical blocks on a_e volume. For a more 
detailed description of both file and device mode, read the 
appropriate sections in Chapter 11 of the RSX-11M/M-PLUS 
Utilities Manual. 


To produce the results shown in Example 18-3, a directory 
file 203054.DIR was copied from UFD [@%,@] into UFD [305,383]. The 
DMP utility was then used on the file [395,303]203054.DIR to dump 
the header of that file. The three sections of the file header 
(header, identification, and map areas) provide useful information 
for the user, and especially the operating system. The header 
area provides the file sequence number (1335,3) which is used _ to 
locate the file on the volume, the file owner ([395,383]), the 
file protection word ([REWD,RWED, RWED,R]), and other information. 


The identification area supplies the file name, type, 
revision number, the date and time of creation, and the date and 
time of last revision. The DCL command, DIRECTORY, uses’ this 
information from the header of the UFD file to provide the listing 
you see at your terminal when you issue the command. 
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Example 19-4 shows the results of dumping the same directory 
file in Octal Word format. The numbers’ in the first column 
represent the virtual disk addresses for the data that follows. 
Across the row is the octal representation of each word of data in 


the file. 
Example 19-5 shows the same directory file dumped in Radix-5@ 
format; information in the file header is stored in Radix-5@ 


format. To use the dump program efficiently, the user must’ know 
how the data is stored in the file. 


Command Format 


>RUN $DMP 
DMP > TI: =305303.DIR/R5 


ee ee Oe ee 


Command to invoke the Dump program 


Output file specification 
Delimiter 


Input file specification 


A dump switch to specify a mode 
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Table 19-9 DMP Switch Format 


H T — ASCII 
Cee EUR cone 
1 0 1 2 4 — OCTAL BYTES 
044124 — OCTAL WORD 


TK-7710 


Figure 18-9 How the DMP Program Interprets 16 Bits 
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DUMP OF DB2:[(305,303]203054,DIR31 © FILE ID 1335,3,0 
FILE HEADER 


HEADER AREA 


H,IDOF 027 

H.MPOF 056 

H.FNUM, 

H.FSEQ (1335,3) 

H,FLEV 401 

H.FOWN (305,303) 

H,FPRO CRWED,RWED,RWED,R) 
H.UCHA 200 = UC,.CON 
HeSCHA 000 = 

H.UFAT 


F.RTYP O01 = RFIX 
F,RATT 000 = 
FeRSIZ 20 = 16, 


F.HIBK H:0 L:000002 = 2, 
F.EFBK H:0 L:000003 = 3, 
F.FFBY 0O= Q, 
(REST) 
000000 000000 000000 000000 000000 900000 000000 000000 
000900 
IDENTIFICATION AREA 
I,FNAM, 
I,FTYP, 
I.FVER 203054 eDIRi 
I.RVNO 1 
I.RVDT 16=SEP#8} 
I.RVTI 11:07:52 
I.CRDT 16°SEP=81 
I,CRTI 11:07:52 
I.EXDT - - 
MAP AREA 
M.ESQN 000 
M.ERVN 000 
M.EFNU, 
M.EFSO (0,9) 
M.CTSZ 001 
M.LBSZ 003 
MUSE 002 = 2, 
M,.MAX 314 = 204, 
MeRTRV 
SIZE LBN 
26 H2000 L:024104 = 10308, 
CHECKSUM 


H.CKSM 061747 


Example 10-3 Directory File Header Dump 
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DUMP OF DB2:(305,303]203054.DIR?1 = FILE 1D 1335,3,9 
VIRTUAL BLOCK 0,900001 = SIZE 512. SYTES 


000900 000152 000076 000000 071620 143245 000000 074742 000001 
000020 001172 900025 000000 004640 000000 000000 100003 000002 
000040 001201 000053 000000 004640 000000 000000 074742 000002 
000060 003047 000111 000000 004640 000000 000000 014474 000001 
000100 003060 000020 000000 055210 000000 000000 100003 000002 
000120 003061 000011 000000 055210 000000 000000 074742 000002 
000140 001533 000245 000000 054204 000000 000000 100003 000003 
000160 003123 000054 000000 055210 076452 000000 100003 000002 
000200 003124 000017 000000 055210 076452 000000 074742 000002 
000220 003125 000100 000000 015370 000000 000000 100003 000002 
000240 003126 000010 000000 015370 000000 000000 074742 000002 
000260 003127 000046 000000 015370 076452 000000 100003 000002 
000300 003131 000012 000000 015370 076452 000000 074742 000002 
900320 003133 000037 000000 015370 000000 000000 014474 000002 
9000340 003134 000014 000000 962204 000000 000000 100003 000002 
000360 003136 000061 000000 062204 000000 000000 074742 000002 
900400 003143 000155 000000 062204 000000 000000 014474 000002 
000420 003145 000012 000000 021300 000000 000000 100003 000002 
000440 003154 000150 000000 055251 054374 000000 100003 000002 
000460 003157 000011 000000 055254 000000 000000 100003 000002 
000500 003277 000044 000000 055400 000000 000000 100003 000002 
000520 003353 000002 000000 954010 000000 000000 100003 000002 
000540 003355 000002 000000 054353 017500 000000 100003 000002 
000560 003371 000002 000000 046166 000000 000000 100003 000002 
900600 003401 000002 000000 046547 000000 000000 100003 000002 
000620 003411 000002 000000 051272 000000 000000 100003 000002 
000640 003441 000023 000000 011665 090000 000000 100003 900002 
000660 003453 000002 000000 010155 000000 000000 100003 000002 
000700 003457 000002 000000 077353 000000 000000 100003 000002 
000720 003465 000002 000000 047006 000000 000000 100003 000002 
000740 003473 900002 9000000 024263 000000 000000 100003 000002 
000760 003475 000002 000000 024261 000000 000000 100003 000002 


Example 19-4 Directory File Dumped in Octal Word Mode 
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ADVANCED MAINTENANCE OPERATIONS 


DUMP OF DB2:(305,303])203054,DIR31 = FILE ID 1335,3,0 


000000 
000020 
000040 
900060 
000100 
000120 
000140 
000160 
000200 
000220 
000240 
000260 
000300 
000320 
000340 
000360 
900400 
000420 
000440 
000460 
000500 
000520 
000540 
000560 
000600 
000620 
000640 
000660 
090700 
000720 
000740 
000760 


VIRTUAL BLOCK 0,000001 = SIZE 512, BYTES 


BZ AV RSX 11M STB A 
04 U AUX TSK B 
PA AC AUX STB B 
90 «6A3 AUX DAT A 
9X P NSP TSK B 
9Y I NSP STB B 
US DE NFT TSK Cc 
AS AD NSP TAB TSK B 
AT 0 NSP TAB STB B 
AU AX DLX TSK B 
AV H DLX STB B 
AW 8 DLX TAB TSK 5 
AY J DLX TAB STB B 
As 1 DLX DAT B 
A. L PCL TSK B 
AO AI PCL STB B 
AS B/ PCL DAT B 
A 7 J EVP TSK B 
AAD BX NTI NIT TSK 8 
AAG I NTL TSK 8 
ACG 6 NvP TSK B 
ADK B NCP TSK B 
ADM i) NIC E TSK B 
ADY 5 LIN TSK 8 
AD3 B LOO TSK B 
AEA B MIR TSK B 
AEY 5s CFE TSK B 
AES 8 BYE TSK B 
AE9 B TLK TSK B 
AFE B LSN TSK B 
AFK B FTS TSK B 
AFM B FTQ TSK B 


Example 18-5 Directory File Dumped in Radix-5@ Mode 


LEARNING ACTIVITIES 


READ the following in the RSX-11M/M-PLUS 


Utilities Manual: 


e Chapter 11, File Dump Utility (DMP) 


e Chapter 4, File Transfer Program 
(FLX) 


READ the following sections in the 


RSX-11M/M-PLUS Command Language Manual: 


e 2.5, Show Queue 
e 4.4.2, Print 


DO Written Exercises 12 through 16 for 
this module. 
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ADVANCED MAINTENANCE OPERATIONS 


PROGRAM MAINTENANCE 
Comparing the Contents of Two Files 
File Compare Utility (CMP) 


The File Compare Utility (CMP) compares the contents of two 
ASCII files to determine their differences. CMP reads the two 
input files, comparing them line-by-line, and generates a _ listing 
showing the difference. 


The DCL command to invoke the utility is DIFFERENCES which is 
shown in the command format below. The /OUTPUT qualifier 
indicates that the differences should be placed in a file with the 
name ODIF.DIF. If you want the output to come to the terminal, 
omit the /OUTPUT qualifier. The next two file specifications 
indicate which files are to be compared. 


Example 19-6 shows the contents of two ASCII files. Using 
these two files as input to the CMP produces the results found in 
Example 19-7. 


Example 19-7 shows the standard output format, indicating the 
lines that are different between the files. 


Example 19-8 is an example of the second output format 
available. On lines 6, 8, and 13-17, an exclamation point appears 
to the right of the line number. This character is used _ to 
represent a change bar, and indicates which lines in the second 
input file differ from the first input file. 


Command Format 


> DIFFERENCES / OUTPUT: DIF.DIF SOURCE.MAC; 1 SOURCE.MAC;2 
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ADVANCED MAINTENANCE OPERATIONS 


ulus 


%, 


>» TYPE COMPARE. TXT 

THIS IS A TEST TO SHOW THE RESULTS OF THE COMPARE 
FILE UTILITY (CMP). THIS UTILITY COMPARES TWO 

ASCII FILES. THE FILES ARE COMPARED LINE BY LINE TO 
DETERMINE WHETHER PARALLEL RECORDS ARE IDENTICAL. 
USING CMP,» YOU CAN FERFORM THE FOLLOWING FILE- 
COMPARE FUNCTIONS? 


GENERATE A LISTING SHOWING THE DIFFERENCES 
BETWEEN THE TWO FILES. EACH DIFFERENCE IS 
LISTED AS A FAIRS FIRST» THE LINES FROM 
THE FIRST FILE THAT ARE BEING COMPARED TO 
LINES IN THE SECOND FILE» THEN THE LINES 
FROM THE SECOND FILE. 


GENERATE A LISTING IN THE FORM OF ONE LIST» 
WITH DIFFERENCES MARKED BY CHANGE BARS. 


GENERATE OUTPUT SUITABLE FOR INFUT TO THE SLF 
UTILITY. THIS OUTPUT CONTAINS THE SLP COMMANDS 
AND INPUT REQUIRED TO MAKE THE FIRST INPUT 

FILE IDENTICAL TO THE SECOND INPUT FILE. 


>TYPE CMP.TXT 

THIS IS A TEST TO SHOW THE RESULTS OF THE COMPARE 
FILE UTILITY (CMP). THIS UTILITY COMPARES TWO 

ASCII FILES. THE FILES ARE COMPARED LINE BY LINE TO 
DETERMINE WHETHER PARALLEL RECORDS ARE IDENTICAL. 
USING CMP» YOU CAN PERFORM THE FOLLOWING FILE- 
COMPARE FUNCTIONS? 


GENERATE A LISTING SHOWING THE DIFFERENCES 
BETWEEN THE TWO FILES. EACH DIFFERENCE IS 
LISTED AS A PAIRS FIRST» THE LINES FROM 
THE FIRST FILE THAT ARE BEING COMPARED TO 
LINES IN THE SECOND FILE» THEN THE LINES 
FROM THE SECOND FILE. 


GENERATE A LISTING IN THE FORM OF ONE LIST» 
WITH DIFFERENCES MARKED BY CHANGE BARS. 


GENERATE OUTPUT SUITABLE FOR INPUT TO THE SLF 
UTILITY. THIS OUTPUT CONTAINS THE SLP COMMANDS 
AND INPUT REQUIRED TO MAKE THE FIRST INFUT 

FILE IDENTICAL TO THE SECOND INPUT FILE, 


CMP PROVIDES SWITCHES THAT ALLOW YOU TO CONTROL COMPARE 
PROCESSING. USING THESE SWITCHES» YOU CAN CONTROL 
COMPARISON OF BLANKS» TABS, FORM-FEEDS, AND COMMENTS. 
YOU CAN ALSO CONTROL LINE NUMBERING AND THE NUMBER OF 
LINES REQUIRED FOR CMP TO CONSIDER THAT A MATCH IS MADE 
BETWEEN LINES IN THE TWO FILES. 

? 

> 


Example 18-6 Two Similar ASCII Files 
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ADVANCED MAINTENANCE OPERATIONS 


>DIFFERENCE/OUTPUTSDIF.TXT COMPARE.TXT CMP.TXT 
>TYPE DIF.TXT 
KXXERAKAARAAKA EKA RARERA ERA SA AERA KK ER EERE KER ERE 
1) DBOSCSO5r 303 ICOMPARE. TXT#1 
RREREAARKRKAKKKE 
2) DBOSC3IOS+ 3OSICMP.TXT#2 
23 CMF FROVIDES SWITCHES THAT ALLOW YOU TO CONTROL COMPARE 
24 PROCESSING. USING THESE SWITCHES» YOU CAN CONTROL 
25 COMPARISON OF BLANKS, TABS, FORM-FEEDS» AND COMMENTS. 
26 YOU CAN ALSO CONTROL LINE NUMBERING AND THE NUMBER OF 
27 LINES REQUIRED FOR CMP TO CONSIDER THAT A MATCH IS MADE 
28 BETWEEN LINES IN THE TWO FILES. 


1 differences found 
DIF .TXT/BL/FF=COMPARE. TXTsCMP. TXT 
>DIFFERENCE/OUTPUTSDIF.TXT/CHANGE.BAR COMPARE.TXT CMF.TXT 
>TYPE DIF.TXT 
KKXKKKKKKAKEKRKEKRKKAKKKKKKAAKKKK KKK KKK EK KAKKKKKE 
1) DBO?CIOSs SOJICOMPARE,. TXT#1 
KKXKKKKKKKAKKKKK 
2) DBOSC3IOSr3OSICMP.TXT#2 
23 CMP FROVIBES SWITCHES THAT ALLOW YOU TO CONTROL COMPARE 
24 PROCESSING. USING THESE SWITCHES: YOU CAN CONTROL 
20 COMPARISON OF BLANKS, TABS, FORM-FEEDS» AND COMMENTS. 
26 YOU CAN ALSO CONTROL LINE NUMBERING AND THE NUMBER OF 
27 LINES REQUIRED FOR CMF TO CONSIDER THAT A MATCH IS MADE 
28 BETWEEN LINES IN THE TWO FILES. 


i differences found 
DIF.TXT/BL/FF/VB=COMPARE. TXTsCMP. TXT 


.. 
a 


Example 18-7 Compare Program Output Between Two ASCII Files 
(Standard Format) 


1 eTITLE FIGI 

2 TEXT: eASCII /STRY THIS, DID IT WORK?/ 
3 RO=%0 

4 R1i=%&1 

5 R2=%2 

6 ! DOT=’, 

8 Li BUFF s »BLKB *p80 

9 eEVEN 

11 ST: MOV #TEXT,RO 
12 MOV #BUFF,R1 
13 =! MOV #DOT,R2 

14 ! LOOPS MOVB (RO)+,CR1) 
i5 ! CMPB CR1I)D+,R2 
16 «6! BNE LOOP 

17! eEND 


2 DIFFERENCES FOUND 
PROG.DIF/CB=PROG.MAC;2,PROG.MAC33 


Example 18-8 Change Bar Format 
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ADVANCED MAINTENANCE OPERATIONS 


LEARNING ACTIVITIES 
READ Chapter 12, File Compare Utility 
(CMP), in the RSX-11M/M-PLUS Utilities 
Manual. 


READ Section 4.4.5, Differences, in the 
RSX-11M/M-PLUS Command Language Manual. 


DO Written Exercise 17 for this module. 
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APPENDIX A 
BATCH JOBS 
(M-PLUS ONLY) 


BATCH JOB FILE 


In addition to the Indirect Command File Processer, the 
RSX-11M-PLUS Operating System has another means of automating a 
process. The Batch File Processor is like the Indirect Command 
File Processor in that it is able to read and then process 
commands from a file. Because the job is run from a virtual 
terminal, your terminal is free to do other tasks. 
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APPENDIX A BATCH JOBS (M-PLUS ONLY) 


BATCH Command Line 


The following command line format shows how to write a_ batch 
command. The dollar sign in the first position is necessary to 
indicate that the line is to be interpreted as a Batch command. 
If the dollar sign is not present, the line is considered to be 
data. The first command in the Batch file is JOB (mandatory) and 
marks the beginning of the _ job. The last command is EOJ 
(mandatory) which indicates the end of the job. What comes in 
between is dependent upon the process you are automating, and will 
include some or possibly all of the commands listed in Table A-l. 


Command Format 


> ${START:][PRINT DELTAX.TXT] = 
°. 8 (O ° ° 


& Batch processor symbol indicating that the line following is 
to be interpreted as a DCL command. 


2 | Optional label (1 through 6 characters terminated by a_ colon) 
used to mark a position in the command file to which a GOTO 
statement may refer. 


Any DCL or MCR command except LOGIN, LOGOUT, HELLO and BYE. 


Character (hyphen) to indicate the command will be continued 
on the next line. 
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: 
Se 
me 


.APPENDIX A BATCH JOBS (M-PLUS ONLY) 


Batch Commands 


cquggemeuneceme: 


uum memsnera aman 2 
ieee eae: = 
Siig 2 iia se 
a 
i 


Table A-1l 


oo 
ee SS. 
: 


: 


ne : 
os 


; : 
pit 
oe 


oe 


ae 


aS 
fees 
Pog fe 


so 
oe 
Ben Seas 


oe 
— 


85 


ees a 

oe : 

See. : 
ee See Soa a: 
ee — ee 
- — 
oS ee OS 
- 

ee : 
oS 


aes 


oe 
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APPENDIX A BATCH JOBS (M-PLUS ONLY) 


PROCESSING THE BATCH FILE 


After you define the process and translate it into a 
corresponding Batch file, the next step is to submit the batch job 
for processing. The following command format shows how to. do 
this. 


The SUBMIT command places your job in the Batch queue, which 
the Queue Manager checks periodically for jobs to run. 


Depending upon the SUBMIT command qualifiers you use, (Table 
A-3) and the number of jobs in the Batch queue, your job may 
either start up immediately, or at a later’ time. The /AFTER 
qualifier allows you to specify the time at which you wish the 
Queue Manager to consider your job for processing. 


Once a job is in the queue, you must use the SET QUEUE, 
RELEASE/JOB, DELETE/JOB or SHOW QUEUE to display, delete or change 
the characteristics of the job (Table A-4). 

The Batch Processor automatically provides a record of the 
activity generated when processing a job, which is called the log 
file. Unless you specify otherwise, this log file prints on your 
system's line printer after processing is complete, and then is 
deleted. 


Example A-1 shows a Batch file and the log file the Batch 
processor creates when processing the file. 


Command Format 


>SUBMIT/JOB:BATRUN BATCH.CMD,PROCESS.CMI 
° e 6 ° e 


Command to queue a job for processing by a batch processor 


Command qualifier 


File specification of file from which batch commands’ will be 
read. Default file type is .CMD. 


File specification delimiter 
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APPENDIX A BATCH JOBS (M-PLUS ONLY) 


Table A-2 Exit Status 


Status Code ; 


Task su 
_ possible 


‘Results unlikely 
One or more 


Table A-3 Submit Command Qualifiers 


Sa oe 


Maer Wants Te 6 
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APPENDIX A BATCH JOBS (M-PLUS ONLY) 


Table A-4 Changing the Batch Queue 


Ss 
a 


Examples A-1l and A-2 show how Batch commands can be organized 
to automate a process. Example A-1 allocates a disk drive, mounts 
the volume and performs a full directory on the volume, sending 
the output to the line printer. Then the volume is dismounted, 
and the drive deallocated. . 


Example A-2 runs a task called WONDER. If a severe error 
occurs, a message is sent to terminal number 19 indicating that an 
error has occurred, and the run will end. If an error occurs, a 
message iS sent to terminal number 18, and the task OLD is run. 
If a warning occurs, a message is sent to the terminal and _ the 
command file terminates. 
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APPENDIX A BATCH JOBS (M-PLUS ONLY) 


$JOB PRTJOB [305,303] 

S!THIS IS A BATCH CONTROL FILE THAT WILL PRINT ALL MY 

SiMY MACRO SOURCE FILES. WHEN I SUBMIT THIS FILE FOR PROCESSING 
S$!1 WILL USE THE /AFTER QUALIFIER OF THE SUBMIT COMMAND TO 
S!DELAY THE EXECUTION UF THE BATCH FILE UNTIL AFTER NORMAL 
S!WORKING HOURS SO THAT I wON’T TIE UP THE PRINTER, 


SPRINT *,MAC 


$E0J 


QMG Batch Job = PRTJOB BPR V8e 24eJANwB2 11817 Page 1 


Processor BAPO 


11217298 


44217818 


Example A-1l 


$JOB PRTJOB (305,343) 


User Job © PRT JOB Teeminal VT2e 


UIC 2 [385,383] 


TERM 


RSX*L1iM=PLUS VO2 BLE [2,54] System KERMIT 


RARER ERERHERRERERHERAEKERAEARREEARERRERKRARKEHEREKHERKKERE 
* * 


Welcome to RSXeiIM=PLUS beteh 
Version 2 Bese level 8 


® 
* 
* 
fe This {9 file LBG(t,2] BATCH. TXT 
* 
5 


RE CKRRARERKEEREAHAREERREREERAERRRKARERNKHEKEEAEKEREEKKKEKHE 


SiTHYS IS A BATCH CONTROL FILE THAT WILL PRINT ALL MY 


S\MY MACRO SOURCE FILES, WHEN J SUBMIT THIS FILE FOR PROCESSING 


S|I1 WILL USE THE /AFTER QUALIFIER OF THE SUBMIT COMMAND TO 
S{DELAY THE EXECUTION OF THE BATCH FILE UNTIL AFTER NORMAL 
S)WORKING HOURS 80 THAT I WON°T TIE UP THE PRINTER, 

SPRINT #, MAC 

PRI © Job 6667 name "PRTJOB ", submitted te queue "PRINT * 
ge0J 


Conmect times 1 minutes 
CPU eime used? 2 seconds 
Tesk totels 6 


Batch Control File to Print MACRO Source Files 
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APPENDIX A BATCH JOBS (M-PLUS ONLY) 


$! THIS BATCH J0B WILL GET A FULL DIRECTORY LISTING 

$8! OF AN PLO{ DISK THAT IS ALREADY LOADED AND SPUN UP, 
$! 

$SET TERMINAL MCR 

SALL DL13 

$SMOU NLIsIMREADY 

$PIP LPOS=DLIs(*,*)] /FU 

$OMD DOL13 

SOEA DLis 

$£OJ 


$JOB AONE[303,14] 
$! IF COMMAND EXAMPLE 


SRUN WONDER, TSK 

SIF SEVEREERROR THEN GOTO BOMB 
SIF ERR THEN GOTO ALAS 

SIF WARNING THEN GOTU OKAY 


$GOTO REST {SUCCESS ASSUMED 
$BOMBs 

$8RO TT103 SEVERE ERROR, RUN ENDS 
$STOP 

$SALAS$ 


S$BRO TT10:s ERROR RUNNING OLD,TSK 
SRUN OLO.TSK 

$GOTO REST 

SOKAY$ 

S$8RO TTIOSWARNING RECEIVED 
SREST:EOJ 


Example A-2 Sample Batch Command Files 
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